Skip to content

Docker Sandboxes (sbx)

Docker Sandboxes (sbx) runs AI coding agents, such as OpenCode, Claude Code, and Codex, in isolated sandboxes. Each sandbox is a lightweight virtual machine (microVM) with its own filesystem, network, and Docker daemon.

The agent can install packages, build images, and start containers without touching your host. It can see only the project folder you share with it, and a network policy controls which sites it can reach.

What it's used for:

  • Letting an agent work on its own safely. Agents in a sandbox run without asking for permission on every command, so a mistake or a bad package stays inside the sandbox.
  • Keeping the host clean. Tools, dependencies, images, and containers the agent installs stay inside the sandbox and are removed with it.
  • Controlling network access. Allow only the sites the agent needs, and block or review everything else.
  • Keeping credentials out of the agent's reach. API keys stay on the host; a host-side proxy adds them to outgoing requests.
  • Running several agents side by side. Each sandbox is separate, and clone mode gives each agent its own copy of a Git repository.

sbx doesn't need Docker Engine or Docker Desktop on the host.

Requirements

  • Linux on a 64-bit Intel/AMD or ARM processor.
  • KVM hardware virtualization for local sandboxes. Cloud sandboxes don't need KVM.
  • A Docker account.

Docker officially supports sbx on Linux only for Ubuntu 24.04 and later. Debian 13 isn't officially supported, but Docker's Linux tarball installs on it.

Check virtualization support

dpkg --print-architecture          # should print amd64 or arm64
grep -Ec '(vmx|svm)' /proc/cpuinfo # should print a number above 0
lsmod | grep kvm                   # should show kvm_intel or kvm_amd
ls -l /dev/kvm

If the CPU check prints 0 or /dev/kvm doesn't exist, turn on Intel VT-x or AMD-V in the BIOS/UEFI. If Linux runs in a virtual machine, that VM needs nested virtualization.

Add your user to the kvm group:

sudo usermod -aG kvm "$USER"

Sign out and back in, or run newgrp kvm in the current terminal.

Install on Debian 13

Docker's Debian apt repository doesn't include the docker-sbx package, so install from the release tarball.

For Intel or AMD (amd64):

cd /tmp
curl -fLO https://github.com/docker/sbx-releases/releases/latest/download/DockerSandboxes-linux-amd64.tar.gz
tar -xzf DockerSandboxes-linux-amd64.tar.gz
./docker-sbx/install.sh

For ARM, use DockerSandboxes-linux-arm64.tar.gz in both commands.

The installer doesn't need sudo. It installs sbx in ~/.docker/sbx/bin. Add that directory to your PATH:

echo 'export PATH="$HOME/.docker/sbx/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
sbx version

If you use zsh, add the line to ~/.zshrc instead.

Updates

A tarball install doesn't update itself. To update, download the latest tarball and run install.sh again.

Install on Ubuntu 24.04 or later

Add Docker's apt repository and install the package:

curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt install docker-sbx

To install Docker Engine at the same time, run curl -fsSL https://get.docker.com | sudo SBX=1 sh instead.

First run

Check the installation, then sign in to Docker. sbx login opens a browser:

sbx diagnose
sbx login

Choose a network policy. Balanced allows common development services, such as package registries and AI providers, and blocks other sites unless you approve them:

sbx policy init balanced

If you skip this step, the first sbx run asks you to choose.

Start an agent in a project folder:

cd ~/projects/my-app
sbx run --name my-app opencode

The first run is slower while the sandbox image downloads. Later runs start in seconds.

The current folder is shared read-write, and the agent's edits appear in your project files right away. Review them with git diff before committing.

Available agents: claude, codex, copilot, cursor, devin, docker-agent, droid, kiro, opencode, and shell.

Everyday commands

Task Command
Open the interactive dashboard sbx
List sandboxes sbx ls
Reconnect to a sandbox sbx run --name my-app
Leave the agent running Press Ctrl+\
Open a shell in a sandbox sbx exec -it my-app bash
Run a command as root sbx exec -u root my-app apt-get update
Copy a file into a sandbox sbx cp ./notes.txt my-app:/home/agent/
Copy a file out of a sandbox sbx cp my-app:/home/agent/output.log ./
Stop a sandbox and keep its state sbx stop my-app
Delete a sandbox sbx rm my-app
Remove all stopped sandboxes sbx prune
Show disk usage sbx df

sbx cp requires absolute paths inside the sandbox.

Deleting a sandbox removes everything installed inside it. Files in the shared project folder stay on your host.

Credentials

Store provider API keys with sbx secret set. The command prompts for the key, so it doesn't end up in your shell history:

sbx secret set anthropic
sbx secret set openai
sbx secret set github --command 'gh auth token'
sbx secret ls

Built-in services: anthropic, copilot, cursor, devin, droid, github, google, groq, mistral, nebius, openai, openrouter, and xai.

The sandbox never receives the real key. A host-side proxy adds it to requests sent to that provider.

Secrets are used by sandboxes created after you store them. Recreate an existing sandbox to pick up a new secret.

Network policy

sbx policy ls                                   # show active rules
sbx policy allow network registry.npmjs.org     # allow one host
sbx policy allow network "*.example.com"        # allow its subdomains
sbx policy deny network tracking.example.com    # block a host
sbx policy log my-app                           # show allowed and blocked requests

Deny rules take precedence over allow rules. Add --sandbox my-app to apply a rule to only one sandbox.

Examples

Run a throwaway agent

--rm deletes the sandbox when you exit the agent:

cd ~/projects/my-app
sbx run --rm opencode

Share extra folders read-only

Mount reference material without letting the agent change it:

sbx run --name my-app opencode . ~/projects/shared-docs:ro

Use PATH:TARGET to choose where a folder appears inside the sandbox:

sbx run --name my-app opencode . ~/datasets:/workspace/data:ro

Give the agent its own copy of a Git repository

Clone mode works on a private copy of the repository instead of your working tree. This is useful when several agents work on the same repository:

cd ~/projects/my-app
sbx run --clone --name my-app-feature opencode

Set --clone when you create the sandbox. Deleting a clone-mode sandbox deletes its clone and any unpushed changes.

Open a web app running in the sandbox

Publish a port when creating the sandbox, so localhost:3000 on the host reaches port 3000 in the sandbox:

sbx run --name web-app -p 3000:3000 opencode

For an existing sandbox, publish it separately:

sbx port publish web-app 3000:3000
sbx port ls web-app

Published ports listen only on localhost by default.

Use a plain shell sandbox

Use the shell agent for an isolated Linux environment without an AI agent:

sbx run --rm shell

Use OpenCode with a company AI gateway

Sandboxes don't read your host's ~/.config/opencode configuration. For an OpenAI-compatible gateway that isn't a built-in service, store its key as a custom secret, allow its host, and add a project-level opencode.json.

Replace ai-gateway.example.com, the key file, and the model name with your own:

tr -d '\n' < ~/.config/opencode/gateway.key | sbx secret set-custom \
  --host ai-gateway.example.com \
  --env GATEWAY_API_KEY \
  --value-stdin

sbx policy allow network ai-gateway.example.com:443

Add opencode.json to the project folder:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "gateway/my-model",
  "providers": {
    "gateway": {
      "name": "Company AI Gateway",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://ai-gateway.example.com/v1",
        "apiKey": "{env:GATEWAY_API_KEY}"
      },
      "models": {
        "my-model": {
          "name": "My Model"
        }
      }
    }
  }
}

Then create the sandbox:

sbx run --name my-app opencode

The sandbox gets a placeholder in GATEWAY_API_KEY. The proxy swaps in the real key only for requests sent to ai-gateway.example.com. sbx secret set-custom is experimental.

Troubleshooting

Symptom Check
sbx: command not found Open a new terminal, or check that ~/.docker/sbx/bin is in PATH
Local sandbox won't start Run sbx diagnose, then check /dev/kvm and membership of the kvm group
Agent can't reach a site Run sbx policy log my-app, then allow the host with sbx policy allow network
New secret isn't used Recreate the sandbox: sbx rm my-app, then sbx run --name my-app <agent>
Host agent settings are missing Sandboxes read only project-level configuration from the shared folder

References