SBX env: consistent and shareable AI sandbox configurations The experimental `sbx env` command lets developers capture a sandbox's agent, tools, resources, and credentials in a shareable `sbxenv.yaml` file, with `schemaVersion: "1"` as the current format version. Running `sbx env run` from a directory containing `sbxenv.yaml` shows an environment plan for approval, then creates a sandbox named `web-app`, installs Playwright and Chromium, and publishes sandbox port 3000 on the host. The documentation warns that the command interface and file format may change, and advises keeping the environment file outside mounted workspace directories. Sandbox environment files A sandbox environment file captures the setup for a local or cloud sandbox in a sbxenv.yaml file. Share the file with project contributors so they use the same agent, tools, resources, and credentials without reproducing CLI flags and setup steps. Note sbx env is experimental. The command interface and file format may change. The examples on this page use local sandboxes unless stated otherwise. For cloud configuration and lifecycle differences, see Use a cloud environment use-a-cloud-environment . Start an environment start-an-environment Keep the environment file outside the directories you mount into the sandbox. That includes the primary workspace and every additionalWorkspaces mount. For example, place it beside your project: web-app-env/ ├── sbxenv.yaml └── web-app/ Create web-app-env/sbxenv.yaml . This example gives the agent a shared environment variable and the Playwright browser-testing tools. It also publishes the application's development port: schemaVersion: "1" name: web-app agent: claude workspace: ./web-app kits: - docker.io/sbx/playwright-kit:latest env: NODE ENV: test ports: - sandbox: 3000 host: 3000 From web-app-env , run the environment: bash $ sbx env run sbx shows an environment plan and asks you to approve it. If you approve the plan, the web-app directory becomes the workspace, while sbxenv.yaml remains outside the sandbox. If the environment doesn't exist, sbx creates a sandbox named web-app , installs Playwright and Chromium, and publishes sandbox port 3000 on the host. It then attaches to the agent. Later runs attach to the existing sandbox. This placement keeps the environment file outside the agent's writable workspace. If you later add additionalWorkspaces , keep sbxenv.yaml outside those directories too. See the workspace guidance workspace for details. Commands commands | Command | Description | |---|---| | sbx env plan PATH... | Shows what applying the environment would change without changing or approving it | | sbx env run https://docs.docker.com/reference/cli/sbx/env/run/ PATH... | Applies the approved plan, creates the environment if needed, and attaches | | sbx env create https://docs.docker.com/reference/cli/sbx/env/create/ PATH... | Applies the approved plan and creates the environment without attaching | | sbx env exec https://docs.docker.com/reference/cli/sbx/env/exec/ PATH... -- COMMAND ARG... | Runs a command in an existing environment without running lifecycle commands | | sbx env rm https://docs.docker.com/reference/cli/sbx/env/rm/ PATH... | Shows a destroy plan, then removes the sandbox and resources named in the plan | To use an environment file, pass its path to sbx env . If you pass a directory, sbx looks for sbxenv.yaml inside it. If you don't pass a path, sbx looks in the directory you run the command from and loads your user defaults set-user-defaults , if present. Every sbx env subcommand accepts --name . This flag sets the sandbox name for that command, overriding the name field in the file or the automatically generated name: bash $ sbx env create --name web-app-test $ sbx env exec --name web-app-test -- npm test $ sbx env rm --name web-app-test Use the same file paths for each command. If you set --name , use that same name for every command that manages the sandbox. Set user defaults set-user-defaults Create ~/.sbxenv.yaml to share settings across your projects. For example, this file selects Claude as the agent and mounts the directory you run sbx env from: schemaVersion: "1" agent: claude workspace: ${{ env.projectDir }} With this file saved in your home directory, run: bash $ cd /projects/web-app $ sbx env run The sandbox mounts /projects/web-app as its workspace. Run the same command from /projects/api , and it mounts /projects/api instead. You don't need a separate sbxenv.yaml in either project. If the project has a sbxenv.yaml , sbx combines it with your user defaults. Project settings override individual default values. Lists such as ports and mcp.servers combine entries from both files. If you pass a file or directory path to the command, sbx skips ~/.sbxenv.yaml . In ~/.sbxenv.yaml , you can set workspace to ${{ env.projectDir }} or a subdirectory such as ${{ env.projectDir }}/src . Other workspace paths aren't accepted in this file. The user defaults file cannot set name . Set the sandbox name in a project environment file or with --name . Reference directories reference-directories You can use ${{ env.projectDir }} and ${{ env.fileDir }} in environment files to insert absolute directory paths. They refer to directories on the host. Project directory project-directory ${{ env.projectDir }} is the absolute path to your project directory. sbx chooses this directory from the command you run: - sbx env run : the directory you run the command from. - sbx env run /projects/web-app : /projects/web-app . - sbx env run /projects/web-app/custom.yaml : /projects/web-app , the directory containing the file. If you pass several paths, the first one sets the project directory. Every file loaded by that command uses the same value for env.projectDir . Use this reference in shared settings that need to point to each project's files. For example, workspace: ${{ env.projectDir }}/src mounts the src directory in whichever project you select. File directory file-directory ${{ env.fileDir }} is the absolute path to the directory containing the environment file where you write the reference. For example, inside /shared/environment.yaml , its value is /shared . Use this reference when an environment file needs to locate files stored alongside it. For example, suppose your setup script is /shared/scripts/setup.sh . Add this lifecycle command lifecycle to /shared/environment.yaml to run the script from /shared : lifecycle: initialize: - command: ./scripts/setup.sh workdir: ${{ env.fileDir }} The command runs from /shared , even if you use this environment file with a project in another directory. Relative workspace paths already use the directory containing the environment file. For example, workspace: ./src in /shared/environment.yaml mounts /shared/src . Both directory references can appear in YAML values, but not in field names or inside the args block. Parameterize an environment parameterize-an-environment Declare inputs in a top-level args block when values need to vary between uses of the same environment file. Each argument must have exactly one of default or required: true : schemaVersion: "1" name: web-app agent: claude args: channel: default: stable description: Release channel enum: - stable - beta endpoint: required: true description: API endpoint cpus: default: "4" pattern: " 1-9 0-9 " env: RELEASE CHANNEL: ${{ env.args.channel }} API ENDPOINT: ${{ env.args.endpoint }} sandboxOptions: cpus: ${{ env.args.cpus }} Reference a declared argument as ${{ env.args.NAME }} anywhere a YAML value can appear. References can't be used in field names or within the args block. An unquoted reference is interpreted as a YAML value after substitution, so the cpus value in this example becomes an integer. Quote a reference to preserve it as a string. All sbx env commands accept repeatable --env-arg NAME=VALUE flags. Values provided with a flag replace defaults from the environment file: bash $ sbx env run --env-arg endpoint=https://api.example.com --env-arg channel=beta Use --env-args-file to load values from a file. Each non-empty, non-comment line must have the form NAME=VALUE : production.args channel=beta endpoint=https://api.example.com bash $ sbx env run --env-args-file production.args You can pass multiple argument files. Later files take precedence over earlier files, and --env-arg flags take precedence over every argument file. Values can contain = , and values in an argument file are read literally rather than expanded by a shell. Argument references and the two directory references are the only variable expressions expanded in an environment file. Shell-style expressions such as ${VAR} aren't expanded from the host environment. Other dollar signs remain literal, so a value such as $PATH:/opt/bin is passed unchanged. Use $${{ env.args.NAME }} to produce the literal text ${{ env.args.NAME }} . Substituted values aren't expanded a second time. Common workflows common-workflows The following examples combine environment file fields into configurations you can adapt for a project. Combine team defaults and personal settings combine-team-defaults-and-personal-settings Keep the shared configuration in a version-controlled environment directory outside the mounted workspace. Put machine-specific settings in a file excluded from version control. For example, commit base.sbxenv.yaml beside the web-app directory: schemaVersion: "1" name: web-app agent: claude workspace: ./web-app env: NODE ENV: development sandboxOptions: cpus: 4 memory: 8g Add local.sbxenv.yaml to .gitignore , then use it for personal settings: env: LOG LEVEL: debug sandboxOptions: memory: 12g Pass both files in merge order: bash $ sbx env run base.sbxenv.yaml local.sbxenv.yaml Nested mappings merge by key, lists concatenate, and values from later files replace earlier scalar values. In this example, the sandbox has four CPUs, 12 GB of memory, and both environment variables. Each relative workspace path resolves from the directory of the file that declares it. Work across multiple repositories work-across-multiple-repositories Mount related repositories alongside the primary project when the agent needs to coordinate changes or consult shared code and documentation: sbxenv.yaml in the directory above the repositories schemaVersion: "1" name: web-platform agent: codex workspace: ./web-app additionalWorkspaces: - path: ./shared-components - path: ./architecture-docs readOnly: true The agent starts in web-app , can modify shared-components , and can read architecture-docs without changing it. The environment file stays outside all three workspaces. Relative paths resolve from the directory of the environment file that declares them. Additional workspaces are mounted directly even when the primary workspace uses clone mode. Reuse an environment in automation reuse-an-environment-in-automation Use the same committed environment for interactive development and automated tasks. Developers attach to the agent with run : bash $ sbx env run Automation can create the sandbox without attaching, run commands in it, and remove it afterward: bash $ sbx env create --auto-approve $ sbx env exec -- npm test $ sbx env rm --force --auto-approve approves the plan for that invocation without recording consent for later invocations. Use the flag for each unattended create or run . The --force flag approves the destroy plan and removes the sandbox even when it is in use. Commands and vault references under secrets resolve on the host, so the automation runner must provide the referenced tools and authentication. The secret values remain outside the environment file. Use a cloud environment use-a-cloud-environment Use sbx --cloud env to manage a cloud sandbox from an environment file. For account and CLI requirements, see Cloud sandboxes https://docs.docker.com/ai/sandboxes/cloud/ . Save this as cloud.sbxenv.yaml : schemaVersion: "1" name: cloud-project agent: shell env: PROJECT NAME: example sandboxOptions: cpus: 2 memory: 4g Review the plan, create the sandbox without attaching, and run a command: bash $ sbx --cloud env plan ./cloud.sbxenv.yaml $ sbx --cloud env run --detached ./cloud.sbxenv.yaml $ sbx --cloud env exec ./cloud.sbxenv.yaml -- printenv PROJECT NAME Cloud environments support agents and kits, environment variables, CPU and memory limits, credentials for supported providers, and host lifecycle commands. Resource limits must match a cloud size https://docs.docker.com/ai/sandboxes/cloud/usage/ choose-resources-and-platform . Lifecycle commands still run on your machine with your privileges. Remove workspace , additionalWorkspaces , clone options, ports , registries , and MCP server definitions from a local file before using it in cloud mode. Cloud environments also reject local sandbox options such as GPU, USB, display, shared skills, templates, and governance profiles. These checks run before host commands or provisioning. Transfer project files with sbx --cloud cp https://docs.docker.com/ai/sandboxes/cloud/usage/ transfer-files or clone a repository inside the sandbox. The plan shows inherited cloud credentials. Sandbox-scoped credentials override account defaults, and credentials declared in secrets override both. Declare literal values or use snapshot: true secrets to resolve a host command or vault reference once. Dynamic secret sources and custom credential providers aren't supported. Credential bindings require cloud support for kit credentials and explicit approval of the kit's injection domains. Changes to secrets and bindings require recreating the sandbox. Updated env values apply to subsequent sessions. Rejoining a running agent keeps that process's environment. Use the same machine, Docker identity, cloud endpoint, and ordered file paths for later commands. sbx login keeps environment state associated with your Docker identity. With DOCKER ACCESS TOKEN , changing the token starts a separate state scope. Remove the environment when you're finished: bash $ sbx --cloud env rm ./cloud.sbxenv.yaml Removal deletes the sandbox and only the secrets provisioned by this environment. Inherited secrets remain. Global bindings remain unless you pass --prune-bindings . For unattended runs, use --auto-approve with create or run , and --force with rm . If creation is interrupted, retry the same command and unchanged declaration within 23 hours. Unresolved requests prevent removal. Follow the recovery message and retain its journal until the original requests are resolved. Review an environment plan review-an-environment-plan sbx env create , sbx env run , and sbx env rm show the changes an environment makes outside its sandbox and ask for approval before applying them. The plan includes host commands, credentials, bindings, MCP registrations, directories, kits, published ports, sandbox options, and environment variables. Run sbx env plan to inspect the apply plan without changing, approving, or recording anything: bash $ sbx env plan The plan compares the environment file with the environment's last applied state and the resources on the host. It omits resources that are unchanged and already approved. Literal secret values appear as SHA-256 digests. Secret references, host commands, environment variables, ports, paths, and binding domains remain visible so you can review them. Interactive approval is recorded for the environment under the sbx state directory. Plans without host commands apply silently on later invocations until the environment changes or a resource is missing. An approval provided with --auto-approve applies only to that invocation. Update an environment update-an-environment For an existing sandbox, sbx env run applies updated env values to the new agent session and reconciles declared MCP servers. Changes to workspaces, kits, ports, secrets, bindings, and sandboxOptions take effect only when the sandbox is next created. Remove the environment with sbx env rm , then create it again to apply those changes. Remove an environment remove-an-environment Secrets and registry credentials are sandbox-scoped. Credential bindings and MCP server registrations are host-global and can be shared by multiple sandboxes. sbx env rm builds a destroy plan from the resources on the host. The plan includes all credentials stored at the sandbox's scope, including credentials that the environment file no longer declares. After approval, sbx removes only the resources named in the plan. Global credential bindings remain unless you pass --prune-bindings . MCP registrations remain available to other sandboxes. Clean up after a failed create clean-up-after-a-failed-create Secret provisioning, binding updates, and MCP server registration occur before the sandbox is created. If sandbox creation fails, scoped secrets remain, and bindings and MCP registrations may also remain. Run sbx env rm with the same paths to remove the scoped secrets. Pass --prune-bindings if you also want to remove the declared global bindings. MCP registrations are host-global and remain after cleanup. File reference file-reference Top-level fields top-level-fields | Field | Type | Required | Default | Description | |---|---|---|---|---| | schemaVersion | string | Yes | None | Schema version. The supported value is "1" | | name | string | No |