docs(sandboxes): add sandbox environments section (sbx env, experimental)

content/manuals/ai/sandboxes/get-started.md

@@ -268,6 +268,9 @@ Then explore:
   publishing.
 - [Workflow patterns](workflows.md) — Git strategies, local services, CI, and
   authenticated tools.
+- [Sandbox environment files](sandbox-environments.md) — declare and share
+  repeatable local sandbox configurations with `.sbxenv.yaml`. Requires `sbx`
+  0.39.0 or later.
 - [Customize with kits](customize/) — package an agent, its tools, and its
   network rules into a reusable definition you launch with a single flag.
 - [Agents](agents/) — the full list of supported agents and how to configure

content/manuals/ai/sandboxes/workflows.md

@@ -569,6 +569,11 @@ CI provider's secret store, use `-t`. For example, in a GitHub Actions step:
 - run: sbx secret set anthropic -t "${{ secrets.ANTHROPIC_API_KEY }}"
 ```
 
+## Sandbox environments
+
+For a declarative alternative to `sbx run` flags, see
+[Sandbox environment files](sandbox-environments.md).
+
 ## Share setup across a team
 
 When several people use sandboxes on the same project, separate repeatable

data/sbx_cli/sbx_env.yaml

@@ -0,0 +1,28 @@
+name: sbx env
+synopsis: |
+    Manage sandboxes declaratively from a .sbxenv.yaml file
+experimental: true
+description: |-
+    Manage a sandbox environment declared in a .sbxenv.yaml file.
+
+    The file describes the agent, optional mixin kits, workspace mounts,
+    environment variables, secrets to provision, and per-service credential
+    bindings. Secrets are provisioned at the environment's sandbox scope so
+    `sbx env rm` can remove everything it created.
+usage: sbx env COMMAND
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for env
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx - Manage AI coding agent sandboxes.
+    - sbx env create - Create a sandbox environment from .sbxenv.yaml
+    - sbx env exec - Execute a command inside a sandbox environment
+    - sbx env rm - Remove a sandbox environment and its scoped resources
+    - sbx env run - Create (if needed) and attach to a sandbox environment

data/sbx_cli/sbx_env_create.yaml

@@ -0,0 +1,30 @@
+name: sbx env create
+synopsis: Create a sandbox environment from .sbxenv.yaml
+experimental: true
+description: |-
+    Read the environment file from PATH (default: current directory),
+    provision its declared secrets at the sandbox scope, merge its credential
+    bindings, and create the sandbox. Use "sbx env run" to attach.
+
+    Each PATH may be a directory (the file is <PATH>/.sbxenv.yaml) or the
+    path to the environment file itself. Passing more than one PATH deep-merges them
+    in order (docker-compose `-f` semantics): later files override earlier ones.
+    Values may reference environment variables with ${VAR} / $VAR (and
+    ${VAR:-default}); see the docs for the full syntax.
+usage: sbx env create [PATH...] [flags]
+options:
+    - name: clone
+      default_value: "false"
+      usage: |
+        Override workspace.clone in .sbxenv.yaml (see 'sbx create --clone')
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for create
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file

data/sbx_cli/sbx_env_exec.yaml

@@ -0,0 +1,68 @@
+name: sbx env exec
+synopsis: Execute a command inside a sandbox environment
+experimental: true
+description: |-
+    Run COMMAND in the sandbox declared in .sbxenv.yaml. The sandbox
+    must already exist (see "sbx env create" and "sbx env run"); a stopped sandbox is
+    started first.
+
+    Arguments before `--` are environment-file paths, following the same rules as
+    the other "sbx env" subcommands: each PATH may be a directory (the file is
+    <PATH>/.sbxenv.yaml) or the path to the environment file itself, and passing
+    more than one deep-merges them in order. Without a `--` every positional
+    argument forms the command and the environment file is read from the current
+    directory.
+
+    Flags match the behavior of "sbx exec".
+usage: sbx env exec [flags] [PATH...] -- COMMAND [ARG...]
+options:
+    - name: detach
+      shorthand: d
+      default_value: "false"
+      usage: 'Detached mode: run command in the background'
+    - name: detach-keys
+      usage: Override the key sequence for detaching a container
+    - name: env
+      shorthand: e
+      default_value: '[]'
+      usage: Set environment variables
+    - name: env-file
+      default_value: '[]'
+      usage: Read in a file of environment variables
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for exec
+    - name: interactive
+      shorthand: i
+      default_value: "false"
+      usage: Keep STDIN open even if not attached
+    - name: privileged
+      default_value: "false"
+      usage: Give extended privileges to the command
+    - name: tty
+      shorthand: t
+      default_value: "false"
+      usage: Allocate a pseudo-TTY
+    - name: user
+      shorthand: u
+      usage: 'Username or UID (format: <name|uid>[:<group|gid>])'
+    - name: workdir
+      shorthand: w
+      usage: Working directory inside the container
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+example: |4-
+      # Run a command in the environment declared in the current directory
+      sbx env exec go test ./...
+
+      # Open a shell
+      sbx env exec -it -- bash
+
+      # Run against explicitly merged environment files
+      sbx env exec .sbxenv.yaml override.yaml -- npm test
+see_also:
+    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file

data/sbx_cli/sbx_env_rm.yaml

@@ -0,0 +1,35 @@
+name: sbx env rm
+synopsis: Remove a sandbox environment and its scoped resources
+experimental: true
+description: |-
+    Remove the sandbox declared in .sbxenv.yaml along with the
+    secret values provisioned at its sandbox scope (service, custom, and registry
+    credentials). Global credential bindings are left in place by default since
+    they are user-wide and may be shared with other sandboxes; pass
+    --prune-bindings to also remove the bindings this environment declares.
+
+    Each PATH may be a directory (the file is <PATH>/.sbxenv.yaml) or the
+    path to the environment file itself. Passing more than one PATH deep-merges them
+    in order (docker-compose `-f` semantics), so the same set used to create the
+    environment resolves to the same sandbox on removal.
+usage: sbx env rm [PATH...] [flags]
+options:
+    - name: force
+      shorthand: f
+      default_value: "false"
+      usage: Skip confirmation prompts
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for rm
+    - name: prune-bindings
+      default_value: "false"
+      usage: |
+        Also remove this environment's bindings from the global credentials.yaml
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file

data/sbx_cli/sbx_env_run.yaml

@@ -0,0 +1,35 @@
+name: sbx env run
+synopsis: Create (if needed) and attach to a sandbox environment
+experimental: true
+description: |-
+    Read the environment file from PATH (default: current directory)
+    and drop into the sandbox shell. If the sandbox already exists it is started
+    and re-attached without re-provisioning; otherwise it is created first
+    (provisioning secrets and bindings) and then attached.
+
+    Each PATH may be a directory (the file is <PATH>/.sbxenv.yaml) or the
+    path to the environment file itself. Passing more than one PATH deep-merges them
+    in order (docker-compose `-f` semantics): later files override earlier ones.
+    Values may reference environment variables with ${VAR} / $VAR (and
+    ${VAR:-default}); see the docs for the full syntax.
+usage: sbx env run [PATH...] [flags]
+options:
+    - name: clone
+      default_value: "false"
+      usage: |
+        Override workspace.clone in .sbxenv.yaml (see 'sbx create --clone')
+    - name: detached
+      shorthand: d
+      default_value: "false"
+      usage: Create/start the sandbox without attaching
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for run
+inherited_options:
+    - name: debug
+      shorthand: D
+      default_value: "false"
+      usage: Enable debug logging
+see_also:
+    - sbx env - (Experimental) Manage sandboxes declaratively from a .sbxenv.yaml file