SBX env: consistent and shareable AI sandbox configurations

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.

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:

$ 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 for details.

Commands #

Command	Description
sbx env plan [PATH...]	Shows what applying the environment would change without changing or approving it
sbx env run[PATH...]	Applies the approved plan, creates the environment if needed, and attaches
sbx env create[PATH...]	Applies the approved plan and creates the environment without attaching
sbx env exec[PATH...] -- COMMAND [ARG...]	Runs a command in an existing environment without running lifecycle commands
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, 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:

$ 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

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:

$ 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

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

${{ 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

${{ 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 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

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:

$ 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:

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 #

The following examples combine environment file fields into configurations you can adapt for a project.

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:

$ 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

Mount related repositories alongside the primary project when the agent needs to coordinate changes or consult shared code and documentation:

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

Use the same committed environment for interactive development and automated tasks. Developers attach to the agent with run:

$ sbx env run

Automation can create the sandbox without attaching, run commands in it, and remove it afterward:

$ 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 sbx --cloud env to manage a cloud sandbox from an environment file. For account and CLI requirements, see Cloud sandboxes.

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:

$ 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. 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 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 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:

$ 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 #

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:

$ 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 #

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 #

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

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 #

Top-level fields

Field	Type	Required	Default	Description
schemaVersion	string	Yes	None	Schema version. The supported value is "1"
name	string	No	<agent>-<workspace-basename>	Sandbox name, overridden by --name
agent	string	Yes	None	Built-in agent or the name of an agent kit
args	map	No	None	Environment arguments. See args
kits	list	No	None	Kits to install at creation. See kits
workspace	string or object	No	No host mount	Primary workspace. See workspace
additionalWorkspaces	list	No	None	Extra directories to mount. See additionalWorkspaces
env	map of strings	No	None	Environment variables for the sandbox
sandboxOptions	object	No	None	Creation options. See sandboxOptions
secrets	map	No	None	Service credentials. See secrets
bindings	map	No	None	Credential injection approvals. See bindings
registries	map	No	None	Registry pull credentials. See registries
mcp	object	No	None	MCP servers. See mcp
ports	list	No	None	Port mappings. See ports
lifecycle	object	No	None	Host commands. See lifecycle

args

args args maps argument names to their declarations. Names must start with a letter or underscore and can contain letters, numbers, underscores, and hyphens. Each declaration must set exactly one of default or required: true.

Field	Type	Default	Description
default	string	None	Value used when the command doesn't supply the argument
required	boolean	false	Require the command to supply the argument
description	string	None	Explanation shown in command output
enum	list of strings	None	Values accepted for the argument
pattern	string	None	Go ( RE2 ) expression matched against the complete argument value

enum and pattern can't be used together.

kits

kits kits accepts local directories, ZIP archives, OCI registry references, and Git URLs prefixed with git+https:// or git+ssh://. Kits can install tools, configure the sandbox, and give the agent project-specific instructions. The examples on this page pair built-in agents with v2 mixins. See Kits v2 for that format, or Version compatibility when selecting v3 kits.

An environment file selects kits and configures a sandbox's host resources. A kit descriptor defines the package itself. The environment file's schemaVersion is independent of the schema version in a kit descriptor.

Explicit relative paths resolve from the directory of the environment file that declares them. These include ., .., paths that start with ./ or ../, and relative paths that end in .zip. Bare references such as organization/kit remain registry references.

Use an object entry to pass arguments to a kit. Set source to the kit reference and map the kit's argument names to values under args:

kits:
  - source: ./kits/tool
    args:
      version: ${{ env.args.channel }}

Remote kit sources must match the kit.allowedSources setting. Docker Hub is allowed by default. To use Git kits from docker/sbx-kits-contrib, add its source:

$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'

The setting replaces the complete allowlist, so include any existing sources you want to keep. For reproducible setup, pin Git kits with the ref URL parameter and OCI kits with an immutable tag or digest.

workspace

workspace When specified as a string, workspace is the path. Use the object form for clone mode. Omit workspace to create a sandbox without a host bind mount. Set workspace: . to mount the directory that contains the environment file that declares it.

sbx mounts the environment file read-only inside the sandbox. Keep the file outside direct-mounted workspaces or directly in a workspace root.

Field	Type	Required	Default	Description
path	string	Yes	None	Workspace directory. Relative paths resolve from the declaring file's directory
clone	boolean	No	false	Use a private clone, equivalent to sbx create --clone

You can override workspace.clone for one create or run invocation with --clone or --clone=false.

additionalWorkspaces

additionalWorkspaces Each additional workspace is mounted after the primary workspace. Relative paths resolve from the directory of the environment file that declares them.

Field	Type	Required	Default	Description
path	string	Yes	None	Directory to mount
readOnly	boolean	No	false	Mount the directory read-only

sandboxOptions

sandboxOptions

Field	Type	Default	Description
template	string	None	Custom sandbox template image
memory	string	None	Memory limit, such as 8g or512m
cpus	integer	0	Number of CPUs. 0 selects the host default
pullPolicy	string	always	Image pull policy: always ,missing , ornever
profile	string	None	Governance profile name
skills	string	Daemon default	Shared agent skills store access: off ,readonly , orreadwrite
display	boolean	false	Provision a display socket for graphical applications
gpu	boolean	false	Pass the host GPU through to the sandbox
usb	list of strings	None	USB device selectors to pass through to the sandbox

For local sandboxes, cpus: 0 allocates all host CPUs, except on Linux arm64 hosts, where the default is capped at 16. Set cpus to an explicit count to request a larger allocation, up to the number of available host CPUs. When creating a sandbox directly with sbx create or sbx run, use --cpus for the same override. Cloud resource limits must match a cloud size.

skills controls access to the shared agent skills store. Set it to off to omit the mount, readonly to mount the store read-only, or readwrite to let the sandbox modify shared skills. If omitted, it uses the daemon's default, which is readonly unless your organization overrides it.

lifecycle

lifecycle The lifecycle block declares commands that run on the host with your user privileges. Use lifecycle commands for work that must happen outside the sandbox, such as creating a workspace, seeding fixtures, or archiving state.

lifecycle:
  initialize:
    - name: Prepare workspace
      command: test -d web-app || git clone https://github.com/example/web-app
      timeout: 5m
  postCreate:
    - command: ./scripts/seed-fixtures.sh
      workdir: web-app
  preRemove:
    - command: ./scripts/archive-state.sh

Lifecycle phases run at the following points:

Phase	Timing
initialize	Before other create or run actions. Runs for every create andrun
postCreate	After a new sandbox is created. For run , before attachment. Does not run when attaching to an existing sandbox
preRemove	After you approve removal and before sbx deletes resources. A failure produces a warning and removal continues

sbx env exec doesn't run lifecycle commands. Commands within a phase run in order and stop at the first failure. Make initialize commands safe to run more than once.

After preRemove commands finish, sbx generates the destroy plan again. Removal stops if the commands introduced changes that weren't included in the approved plan.

Each command requires command and accepts the following fields:

Field	Type	Default	Description
name	string	Command text	Label shown in progress and plan output
command	string	None	Command passed to the user's shell
workdir	string	Project directory	Host working directory. Relative paths resolve from the first file's directory
timeout	string	None	Maximum runtime, such as 90s or5m

Commands inherit the environment of the sbx process and receive the following variables:

• SBX_LIFECYCLE_PHASE
• SBX_ENV_FILE andSBX_ENV_FILES
• SBX_ENV_DIR
• SBX_SANDBOX_NAME
• SBX_AGENT
• SBX_WORKSPACE

The environment file's env values and resolved secrets aren't passed to host commands.

Plans containing lifecycle commands or credential command sources require approval for every invocation by default, even when the command text hasn't changed. Approve one invocation with --auto-approve, skip lifecycle commands with --skip-host-commands, or turn on env.rememberHostCommands to remember approval until the commands change:

$ sbx settings set env.rememberHostCommands true

secrets

secrets secrets maps service names to secret sources. Each entry must set exactly one of value, ref, or command. The secret is stored at the sandbox scope when the environment is created.

Field	Type	Default	Description
value	string	None	Literal secret value
ref	string	None	Vault URI, such as op://Vault/Item/field
command	string	None	Host shell command whose standard output becomes the secret
snapshot	boolean	false	Resolve ref orcommand once on the host and store the result as a literal
refresh	string	None	Resolution policy for ref orcommand , such ason-demand or55m
backend	string	Automatic	Resolver for ref :sdk orcli
noVerify	boolean	false	Skip verifying that a ref orcommand resolves during provisioning

Warning A literal value is visible to anyone with read access to the file. Use a vault URI with ref or obtain the value at runtime with command.

secrets:
  anthropic:
    ref: op://Private/Anthropic/api-key
    refresh: 55m
  github:
    command: gh auth token

Secret commands execute from a fresh temporary directory on the host. Relative helper paths resolve from that directory. Keep helpers and their dependencies outside writable sandbox mounts. Use an absolute path, an absolute host PATH entry, or an explicit change to the helper's private directory. See dynamic secret sources.

For a cloud environment, set snapshot: true on a ref or command source:

secrets:
  github:
    command: gh auth token
    snapshot: true

The command runs on the host after plan approval. The resolved value is stored as a literal secret and doesn't refresh. Recreate the environment to rotate it. Snapshots also work with local environments. A snapshot can't set refresh or noVerify. Cloud snapshots use CLI resolvers for vault references and don't support backend: sdk.

bindings

bindings bindings approves credential injection domains for each service. The environment merges these approvals into the user's global credentials.yaml. Each service can contain an apiKey block, an oauth block, or both. Each block contains a domains list:

bindings:
  github:
    apiKey:
      domains:
        - api.github.com

sbx env rm preserves global bindings by default. Pass --prune-bindings to remove every service binding declared by the environment file.

Warning --prune-bindings deletes the complete global binding entry for every service declared in the environment file. This can affect other sandboxes that share those service bindings.

registries

registries registries maps registry hostnames to pull credentials. Each entry requires secret and accepts an optional username. Both fields accept a secret source with exactly one of value, ref, or command.

When username is omitted, sbx stores a token-only credential. Registries such as GHCR and GitLab accept token-only credentials.

registries:
  ghcr.io:
    secret:
      command: gh auth token

mcp

mcp The mcp.servers list registers servers with the built-in MCP gateway and adds them to the sandbox. MCP registrations are host-global and remain after sbx env rm.

Field	Type	Required	Default	Description
name	string	Yes	None	Server name
url	string	No	None	Remote server URL, registry reference, or OCI reference
command	string	No	None	Command for a local stdio server
args	list of strings	No	None	Arguments passed to command

Each server must set exactly one of url or command.

ports

ports ports publishes sandbox ports when the environment is created. Ports exposed by a kit but omitted from this list receive an ephemeral host port.

Field	Type	Required	Default	Description
sandbox	integer	Yes	None	Sandbox port from 1 through 65535
host	integer	No	Ephemeral	Host port from 1 through 65535
protocol	string	No	tcp4 , ortcp6 for IPv6hostIP	tcp ,tcp4 ,tcp6 ,udp ,udp4 , orudp6
hostIP	string	No	Loopback	Host interface to bind

Set protocol: tcp to bind both IPv4 and IPv6. Leave hostIP unset for a dual-stack binding because an explicit address binds only its own IP family.

If a port can't be published, sandbox creation fails and removes the new sandbox.

source & further reading

docs.docker.com — original article