Get started with Docker Sandboxes

Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system.

This page walks through a typical first session: installing the CLI, authenticating your agent, running a sandbox, isolating the agent's workspace, and cleaning up.

Prerequisites

An API key or authentication method for the agent you want to use. Most agents require an API key for their model provider (Anthropic, OpenAI, Google, and others). See the agent pages for provider-specific instructions.

Docker Desktop is not required to use sbx.

Install and sign in

$ brew install docker/tap/sbx
$ sbx login

> winget install -h Docker.sbx
> sbx login

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

If you need to install sbx manually, download a binary directly from the sbx-releases repository.

sbx login opens a browser for Docker OAuth. On first login (and after sbx policy reset), the CLI prompts you to choose a default network policy for your sandboxes:

Choose a default network policy:

     1. Open         — All network traffic allowed, no restrictions.
     2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

Use ↑/↓ to navigate, Enter to select, or press 1–3.

Balanced is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual rules later. See Policies for a full description of each option.

Note

See the FAQ for details on why sign-in is required and what happens with your data.

Authenticate your agent

Agents need credentials for their model provider. How you provide them depends on the agent.

For Claude Code with a Claude subscription (Max, Team, or Enterprise), no upfront setup is needed — use the /login command inside the sandbox to sign in with OAuth. The session token stays on your host and is injected by a proxy, not stored inside the sandbox.

For agents that use API keys (or if you prefer API key authentication for Claude Code), store the key before starting a sandbox:

$ sbx secret set -g anthropic

This prompts for the secret value and stores it in your OS keychain. A proxy on your host injects the key into outbound API requests so it's never exposed inside the sandbox. See Credentials for details on scoping, supported services, and alternative methods.

To give the agent access to GitHub for creating pull requests or interacting with repositories:

$ sbx secret set -g github -t "$(gh auth token)"

Run your first sandbox

Pick a project directory and launch an agent with sbx run:

$ cd ~/my-project
$ sbx run --name my-sandbox claude

Replace claude with the agent you want to use — see Agents for the full list.

The first run takes a little longer while the agent image is pulled. Subsequent runs reuse the cached image and start in seconds.

You can check what's running at any time:

$ sbx ls
SANDBOX       AGENT    STATUS    PORTS   WORKSPACE
my-sandbox    claude   running           ~/my-project

You can also run sbx with no arguments to open an interactive dashboard. The dashboard shows your sandboxes with live status, lets you attach to agents, open shells, and manage network rules from one place. See Interactive mode for details.

Use clone mode

By default, the agent edits your working tree directly. To give the agent an isolated copy of your repository, use --clone. Because --clone is a create-time flag, remove the existing sandbox first:

$ sbx rm my-sandbox
$ sbx run --clone --name my-sandbox claude

In clone mode, the sandbox keeps a private Git clone inside the microVM and mounts your host repository read-only. The sandbox exposes its clone as a sandbox-<sandbox-name> remote on your host, so you review the agent's commits the same way you'd fetch from any other remote:

$ git fetch sandbox-my-sandbox
$ git log sandbox-my-sandbox/main
$ git diff main..sandbox-my-sandbox/main

When you're ready to create a pull request:

$ git checkout -b my-feature sandbox-my-sandbox/main
$ git push -u origin my-feature
$ gh pr create

For Claude Code, pair --clone with the agents view to dispatch tasks to subagents that each work on their own branch inside the same sandbox:

$ sbx run --clone --name my-sandbox claude -- agents

Clone mode is especially useful when running multiple agents on the same repository in parallel — each works in its own isolated clone without touching your host working tree. See Clone mode for the full workflow, including how to have the agent commit to a dedicated branch.

Manage network access

Your network policy controls what the sandbox can reach. If the agent fails to connect to an API or service, it's likely blocked by the policy.

Check which rules are in effect:

$ sbx policy ls

To allow a specific host:

$ sbx policy allow network -g registry.npmjs.org

With Locked Down, even your model provider API is blocked unless you explicitly allow it. With Balanced, common development services are permitted by default. See Policies for the full rule set and how to customize it.

Clean up

Sandboxes persist after the agent exits. To stop a sandbox without deleting it:

$ sbx stop my-sandbox

Installed packages, Docker images, and configuration changes are preserved across restarts. When you're done with a sandbox, remove it to reclaim disk space:

$ sbx rm my-sandbox

Removing a sandbox deletes everything inside it — installed packages, Docker images, and the in-sandbox Git clone if you used clone mode. Files in your host working tree are unaffected.

Next steps

• Usage guide — sandbox management, reconnecting, multiple workspaces, port forwarding, and more
• Agents — supported agents and configuration
• Customize — build reusable templates or declare capabilities with kits
• Credentials — credential storage and management
• Workspace isolation — what the agent can affect on your host, and how to review changes
• Governance — control outbound access