Sandbox environment files

A sandbox environment file captures the setup for a project 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 requires sbx 0.39.0 or later. The feature is experimental, so the command interface and file format may change in future releases.

Start an environment

Keep the environment file outside the directories you mount into the sandbox. 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

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. See the workspace guidance for details.

Commands

PATH can be a directory or a direct path to an environment file. When you pass a directory, sbx reads .sbxenv.yaml and falls back to .sbxenv.yml. With no path, sbx searches the working directory.

Pass the same set of paths to each lifecycle command so they resolve the same sandbox.

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. The first file controls the base directory for relative workspace paths and the default sandbox name.

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 first environment file. 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
$ sbx env exec -- npm test
$ sbx env rm --force

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.

Update an environment

sbx env run starts and attaches to an existing sandbox without provisioning its secrets and bindings again. For an existing sandbox, the command applies changes to env to the new session and reconciles declared MCP servers. Changes to workspaces, kits, ports, secrets, bindings, and sandboxOptions require you to remove the environment with sbx env rm and create it again.

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 removes the sandbox and its scoped credentials. 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

The loader rejects unknown fields and unsupported schema versions.

Top-level fields

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. See Kits for details.

Remote kit sources must match the kit source allowlist. 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

When specified as a string, workspace is the path. Use the object form for clone mode:

Warning

With direct mount, the agent can modify every file in a workspace. If an environment file is inside a mounted workspace, the agent can change the file that controls later sbx env commands. Store environment files outside all direct-mounted workspaces. Clone mode protects files in the primary repository, but additional workspaces remain direct-mounted.

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

additionalWorkspaces

Each additional workspace is mounted after the primary workspace. Relative paths resolve from the directory of the first environment file.

sandboxOptions

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.

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

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

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.

Each server must set exactly one of url or command.

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.

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