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:
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:
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:
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:
Choose a network policy. Balanced allows common development services, such as package registries and AI providers, and blocks other sites unless you approve them:
If you skip this step, the first sbx run asks you to choose.
Start an agent in a project folder:
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:
Share extra folders read-only
Mount reference material without letting the agent change it:
Use PATH:TARGET to choose where a folder appears inside the sandbox:
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:
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:
For an existing sandbox, publish it separately:
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:
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:
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 |