Trust the Model. Cage the Agent.

If you have started giving coding agents real access to your machine, you have probably felt the same nagging voice when you want them to install packages, run tests, and touch Docker, but you do not want them treating your laptop as a playground. Docker Sandboxes (sbx) is Docker’s answer.

It runs the agent inside a microVM. The model still lives in the cloud. The commands, containers, and stray installs stay in the VM. This is a practical guide for getting Claude Code running in sbx — isolate the agent, not your editor.

What you are actually running

There are three layers. Mixing them up is how this gets confusing.

• Your editor: Cursor or VS Code stays on the host. That window is not inside the sandbox.
• The sandbox: A Linux microVM started by the sbx CLI. It has its own filesystem (except the project you mount), its own network, and its own Docker daemon.
• AI Agent: For example Claude Code a CLI that runs inside that VM. When it “thinks,” it calls Anthropic. When it edits files or runs tests, that happens in the VM.

You will not see this VM in Docker Desktop. sbx is not a host container. List sandboxes with sbx ls, not docker ps. Use this Docker Sandboxes when you want an agent that can install tools and run Docker without owning Homebrew, your host daemon, or files outside the repo.

Why bother

When a Agent normally runs on it can install global packages, start containers on Docker Desktop, and wander outside the repo. In sbx, that flag is the default because the VM is the permission boundary.

• Inside the VM: AI can be aggressive — packages, images, containers, git. All of that dies when you remove the sandbox.
• On the host: Your editor, your toolchain, and everything outside the mounted workspace stay out of reach.
• The exception: The project folder is bind-mounted read-write at the same absolute path. Edits show up in your editor immediately. Review them as a normal git diff.

Tip: Cage the agent when you want permission less coding inside a box, not a prompt that asks before every rm.

Setup

You need three things: the sbx CLI, a free Docker account, and a AI Agent subscription in this example we use Claude. Visit Docker Sandboxes for the setup on your machine.

Then sign in: sbx login. A browser opens for Docker OAuth. This is required even though the CLI is free. If the daemon looks stuck, run sbx diagnose or sbx daemon restart.

Tip: Install sbx once on the host. Do not try to find it as a container in Docker Desktop.

Authenticate your AI agent

sbx ships with several agents out of the box. Launch any of them the same way: sbx run <agent> from your project directory.

• Claude Code: sbx run claude — Anthropic. The rest of this section uses Claude as the example.
• Codex: sbx run codex — OpenAI. Host OAuth via sbx secret set openai --oauth, or store an API key with sbx secret set openai.
• Copilot: sbx run copilot — GitHub Copilot CLI. Store a token with sbx secret set github --command 'gh auth token'.
• Cursor: sbx run cursor — Cursor agent. API key with sbx secret set cursor, or OAuth on first run. (This combo is still rough — see section 7.)
• Gemini: sbx run gemini — Google. API key with sbx secret set google, or sign in inside the sandbox.
• Docker Agent: sbx run docker-agent
• Droid: sbx run droid — Factory.
• Kiro: sbx run kiro
• OpenCode: sbx run opencode
• Shell: sbx run shell — no agent; a bare VM for manual setup or testing.

The full list lives in Docker’s supported agents docs. Swap claude for any name above when you run a sandbox.

Claude example

Claude Code needs an Anthropic account. Pick one path.

• Subscription (Pro / Max / Team / Enterprise): Do nothing on the host. After the sandbox starts, run /login inside Claude. The OAuth token stays on the host; the VM never stores it.
• API key: Run sbx secret set anthropic and paste the key. It goes in your OS keychain. The sandbox sees a placeholder. The host proxy injects the real key on the way out.

The first-run trap: Locked Down

The first launch asks for a global network policy. This applies to every sandbox until you change it.

• Open: All outbound traffic allowed. No restrictions.
• Balanced: Default deny, with common dev sites allowed. The sensible default.
• Locked Down: Default deny. Nothing leaves unless you allow it — including api.anthropic.com.

Locked Down makes Claude look broken: “invalid API key,” or a login that times out in seconds. The agent is fine. The network is a brick wall. If you already picked it: sbx policy allow network "**" or the narrower sbx policy allow network "**.anthropic.com,**.claude.ai". Check with sbx policy ls and sbx policy log.

Start Claude on a project

From the repo you want it to work on:

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

The first start pulls the Claude image and is slow. Later starts are seconds. You land in Claude Code inside the VM. If you skipped the API key, run /login. Claude starts as claude --dangerously-skip-permissions because the VM is the safety boundary. Give it a real job, not a hello-world. Quit with Ctrl+C or /exit. The VM stays. Reconnect with the same command. sbx stop my-project pauses it. sbx rm my-project destroys the VM; host files are untouched.

Direct mode vs clone mode

When your workspace is a git repo, choose how the sandbox receives it.

• Direct (default): Claude writes into your working tree. Instant feedback, easy to review, easy to collide with your own edits.
• Clone (--clone): Claude gets a private clone. Your tree stays clean. Fetch with git fetch sandbox-my-project-exp when you want the work.

Removing a clone-mode sandbox deletes that clone. Fetch first if you care about the commits.

Day-to-day extras

Once the first session works, these are the commands you actually reuse.

• Shell without Claude: sbx exec -it my-project bash — same VM, good for docker ps and logs.
• Publish a port: sbx ports my-project --publish 8080:80 then open the app on the host. Map the port the app actually listens on.
• Dashboard: Run sbx with no arguments. Attach, shell, network rules. Press ?.
• Parallel agents: sbx run claude --name feature-a and sbx run --clone claude --name spike. Each name is a separate VM.
• SSH into the VM (optional): sbx setup ssh then ssh my-project.sbx. Most people leave the editor on the host.

Why cage the agent

The title is three different jobs. The model is the language model in the cloud — it thinks, it never sits on your laptop. The agent is the local program that acts on those thoughts: Claude Code, Codex, Copilot, and the rest. It runs commands, edits files, installs packages. That is the intern with a terminal. The cage is the Docker Sandbox, a microVM around the agent, not around the model. The model still talks to the provider through a proxy on the host. Your project folder is the hatch in the door, shared so you can review a git diff.

Trust the model to think, put the agent in a cage so it can work, and keep the keys on your side of the door. Happy Coding!!!