Docker Sandboxes

Docker Sandboxes run AI coding agents in isolated microVMs. Each sandbox gets its own Docker daemon, filesystem, and network — the agent can install packages, build containers, and modify files without touching your host system. Sandboxes use clone mode: your repository is mounted read-only, and the agent works on a private in-container copy. Cate fetches the agent’s commits back to your host for diffs, PRs, and merges.

Sandboxes are a good fit when you want hard isolation between the agent and your machine, when your IT policies require containerized execution, or when you want agents to run build and test commands without side effects on the host.

How Cate uses sandboxes

You create and own the sandbox. Cate connects, validates, and runs agent sessions inside it — it never creates, deletes, or reconfigures your sandbox. The ownership boundary is explicit:

You own	Cate owns
sbx create, sbx login, sbx policy, sbx secret	Connecting via sbx run / sbx exec
Symlinks for transcript and data redirect	Preflight validation (8 checks before every session)
Provider authentication inside the sandbox	Session lifecycle, health probes, branch propagation
Network policy for MCP bridge access	Sandbox status monitoring and holder management

When a project window opens, Cate starts the sandbox with sbx run and keeps it alive as a holder process. Agent sessions run inside this holder via sbx exec (Claude) or the OpenCode REST API. When the window closes, Cate stops the sandbox based on your shutdown preference.

Prerequisites

• Docker Desktop or Docker Engine installed and running
• sbx CLI installed — brew install docker/tap/sbx on macOS, or sudo apt-get install docker-sbx on Linux
• A Docker account for sbx login
• A git repository already cloned on your host — the sandbox mounts this directory
• Docker Sandboxes subscription — sandboxes require a separate Docker subscription

Set up a sandbox

These instructions create a single sandbox from the claude agent image, then install OpenCode inside it. This gives Cate a sandbox where both Claude and OpenCode sessions work.

Authenticate sbx

sbx login

Verify with sbx ls — it should return without error.

Create a data directory

The sandbox needs a read-write directory on your host for session transcripts and usage data. Create it before running sbx create:

mkdir -p /path/to/data-dir

Use any location you like. A common convention is ~/.cate-sandbox/<repo-name>.

Create the sandbox

sbx create --clone --name <sandbox-name> claude <repo-path> <data-dir>

Placeholder	Example	Purpose
<sandbox-name>	my-project-cate	Stable name Cate uses to connect. Convention: <repo>-cate.
<repo-path>	/Users/me/dev/my-project	Absolute path to your repository on the host. Mounted read-only inside the sandbox; the agent works on a private clone at the same path.
<data-dir>	/Users/me/.cate-sandbox/my-project	Read-write host directory for transcripts and usage data.

The --clone flag is required. Clone mode gives the agent its own copy of the repository while keeping your host files untouched.

Note

These instructions use the claude agent image as the base and then add OpenCode support. If you don’t plan to use Anthropic models, you can start from the opencode image instead — replace claude with opencode in the command above and skip the OpenCode installation step.

Note

Clone mode binds each sandbox to a single repository. Create a separate sandbox for each project you want to run in a sandbox.

Install OpenCode (optional)

The Claude agent image ships Claude Code but not OpenCode. Skip this step if you only use Claude. Without OpenCode installed, OpenCode sessions will fail to launch.

To use OpenCode models (GPT, Gemini, Grok, and others), install it inside the sandbox:

sbx exec -u root <sandbox-name> bash -lc 'npm install -g opencode-ai'

Verify:

sbx exec <sandbox-name> opencode --version

Note

The stock opencode agent image ships a pinned version that may lag behind what Cate requires. Installing via npm in the Claude image gets the latest compatible version. The Claude image already has Node.js, so npm install -g works without additional setup.

Set up data symlinks

Create symlinks inside the sandbox so session transcripts and usage data land on the host-mounted data directory:

sbx exec -it <sandbox-name> bash -lc '
  mkdir -p <data-dir>/claude-transcripts
  ln -sfn <data-dir>/claude-transcripts ~/.claude/projects
'

If you installed OpenCode, add its symlink too:

sbx exec -it <sandbox-name> bash -lc '
  mkdir -p <data-dir>/opencode
  mkdir -p ~/.local/share
  rm -rf ~/.local/share/opencode
  ln -sfn <data-dir>/opencode ~/.local/share/opencode
'

Replace <data-dir> with the same path you used in sbx create. These symlinks redirect:

• Claude transcripts (~/.claude/projects) — .jsonl session logs that Cate reads for Logged Usage
• OpenCode data (~/.local/share/opencode) — the opencode.db database Cate reads for token and cost tracking

Credentials stay inside the sandbox and are never written to the data directory.

Configure network policy

The sandbox needs to reach Cate’s MCP bridge on your host so agents can use Cate’s tools (issue tracking, PR creation, structured choices). Allow this with a network policy:

sbx policy allow network <sandbox-name> localhost:19275

The port (19275) is Cate’s default MCP bridge port. If you’ve changed it in Settings → Advanced, use that port instead.

Then set the bridge URL inside the sandbox so agents know where to connect:

sbx exec <sandbox-name> bash -c \
  "echo 'export CATE_BRIDGE_URL=http://host.docker.internal:19275' >> ~/.bashrc"

Set up provider credentials

Claude (Anthropic):

sbx run <sandbox-name>

Inside the Claude TUI, type /login and follow the OAuth prompts. After authentication, detach with Ctrl-C. Cate manages subsequent sessions.

OpenCode (if installed):

Use sbx secret set to store API keys for the providers you want. The credential is stored in your host’s OS keychain — a proxy injects it into outbound requests so the real key never enters the sandbox.

sbx secret set -g anthropic
sbx secret set -g openai
sbx secret set -g google
sbx secret set -g xai

You only need to set the providers you plan to use. Available services include anthropic, openai, google, xai, groq, aws, and openrouter. See Docker’s credentials documentation for the full list.

Note

Global secrets (-g) only take effect when a sandbox is created. If you add or change a global secret after creating the sandbox, recreate it for the new value to apply. Sandbox-scoped secrets (without -g) take effect immediately.

Configure Cate

Open Settings (gear icon, bottom left) and click into the project’s Runtime settings:

1. Set Runtime to Docker Sandbox
2. Enter the Sandbox Name you used in sbx create
3. Enter the Data Directory path on your host

Cate validates both fields — the sandbox name is checked against sbx ls and the data directory is verified on disk. Once both pass validation, the sandbox is ready.

Extra options

Open terminals in sandbox — When enabled (default), terminal tabs open inside the sandbox. Turn off to open terminals on the host instead.

Run code in sandbox — When enabled (default), run configurations execute inside the sandbox. Turn off to run on the host.

Container Shutdown — Controls what happens when you close the project window:

• On window close (default) — Stops the sandbox immediately
• Manual — Leaves the sandbox running until you stop it yourself

Sandbox status

When a project uses a sandbox, the sandbox status appears at the bottom left of the sidebar. It shows whether the sandbox is starting, running, stopping, or degraded (the holder process died or the MCP bridge is unreachable).

Updating OpenCode

When a new OpenCode version is needed:

sbx exec -u root <sandbox-name> bash -lc 'npm install -g opencode-ai@latest'

No sandbox re-creation needed. The update persists across stop/start cycles.

Removing a sandbox

Fetch any uncommitted work first:

git fetch sandbox-<sandbox-name>

Then remove:

sbx rm -f <sandbox-name>

The data directory on the host is not deleted — transcripts and databases remain on disk.

Troubleshooting

Symptom	Fix
sbx ls shows sandbox as Stopped	Re-open the project window — Cate starts it automatically
Agent can’t reach MCP tools	Re-run the network policy command from Configure network policy
”Sandbox not found” in Cate	Verify the sandbox name in Settings → Runtime matches sbx ls
No cost or transcript data	Re-run the symlink commands from Set up data symlinks
Agent errors immediately	Provider credentials may have expired — re-authenticate per Set up provider credentials
opencode serve fails	Update OpenCode: sbx exec -u root <name> bash -lc 'npm install -g opencode-ai@latest'