Docker Sandboxes (sbx) Guide: Run Claude Code Safely in a microVM

Docker Sandboxes (CLI: sbx) runs AI coding agents inside isolated microVMs instead of directly on the host. This guide explains the isolation boundary and setup path, then focuses on the operational details that still matter: workspace sharing, network policy, secrets, and Git hooks.

Audience and reading path

This guide is for developers who want to run Claude Code / Codex locally for long-running or unattended work without contaminating the host. It covers the isolation boundary, prerequisites, install → login → first Claude run, when YOLO / skip-permissions becomes safer (not magic), and the comparison and adoption checklist. Read it in that order.

---

Four-step first run

1. Confirm OS/hypervisor prerequisites and install sbx
2. Start with one pilot project: try sbx run claude under the Balanced network policy
3. Inspect sbx policy ls and workspace vs --clone
4. Tear down with sbx rm when finished

For lighter OS-level sandboxes vs environment isolation, see also Choosing sandboxes for Claude Code and Codex.

---

1. What Docker Sandboxes Are (microVM + sbx)

Docker Sandboxes is not “just another container wrapper.” Official docs describe a hypervisor-backed microVM per agent runtime. Inside that VM the agent can use a full Docker daemon, its own filesystem, and a constrained network path through a host-side proxy.

Why that matters operationally

• Shared-kernel containers and Docker-socket mounts still leave a large blast radius on the host.
• Host YOLO (--dangerously-skip-permissions on the bare machine) maximizes speed and contamination risk together.
• Sandboxes raise the primary trust boundary to the microVM and keep agent Docker inside the VM.

---

Approach comparison

Approach	Isolation picture	When the agent needs Docker	Typical weakness
Host + skip-permissions	None	Hits host daemon	Maximum host blast radius
Socket mount / DinD-style	Container-centric	Boundary with host daemon gets muddy	Shared kernel / privilege confusion
Docker Sandboxes (sbx)	microVM / hypervisor	In-VM daemon	Shared workspace, performance, policy upkeep

---

Sources and Desktop note

Sources: Docker Sandboxes docs, Security model (as of July 2026). Independent write-ups similarly stress “microVM, not container,” with a per-agent kernel and in-VM Docker engine (e.g. Andrew Lock).

Docker Desktop is not required; the free sbx CLI is enough to start.

---

2. Get started — install through sbx run claude

Short path: prerequisites → install → sbx login → auth → sbx run claude.

Prerequisites (official get-started)

• macOS Sonoma 14+ on Apple silicon
• Windows 11 x86_64 with Hypervisor Platform
• Ubuntu 24.04+ with KVM
• Docker Desktop not required

---

Install examples

# macOS
brew trust docker/tap && brew install docker/tap/sbx

# Windows
winget install Docker.sbx

# Linux (Ubuntu example: apt package docker-sbx + kvm group)
# Follow the official Linux steps for your distro

sbx login

On first login you pick a default network policy:

Policy	Intent	First trial
Open	Broad egress	Often too wide
Balanced	Allow common dev destinations with a deny-by-default posture	Start here
Locked Down	Strict	Only after explicit allows

---

Claude Code

sbx secret set -g anthropic   # or /login OAuth inside the sandbox
cd /path/to/project
sbx run --name my-sandbox claude

# Optional: one-shot prompt / clone + agents view
# sbx run claude -- "fix the failing test"
# sbx run --clone claude -- agents

sbx ls
sbx policy ls
sbx stop my-sandbox
sbx rm my-sandbox

---

Secrets

Pass tokens via sbx secret set rather than dumping raw keys into the agent environment.

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

---

First launch and host surface area

---

Runtime and host surface notes

From independent write-ups and the official FAQ:

• First launch may pull a base image (Claude template) slowly; later runs usually benefit from cache
• By default the agent’s host surface area is mainly the workspace. Packages, images, and containers stay inside the sandbox
• Memory knobs such as --memory exist (default around half of host RAM in one analysis: Andrew Lock)
• Clipboard image paste is opt-in (sbx settings set clipboard.imagePaste true)

---

3. Isolation model — when YOLO gets safer

A microVM is necessary but not sufficient. Official security docs treat the microVM as the primary trust boundary and list five isolation layers:

Five isolation layers

1. Hypervisor — main host boundary (full power, including sudo, inside the VM)
2. Network proxy — deny-by-default; allowed HTTP(S) domains; host localhost and raw TCP/UDP/ICMP generally blocked
3. Per-sandbox Docker Engine — agent Docker stays in-VM
4. Workspace isolation via --clone — stronger than the default direct RW mount
5. Credential isolation — host proxy injects auth headers so raw keys need not live in the VM

---

Practical caveats

• Default direct mount still RW-shares the working tree with the host
• Git hooks may not show up in git diff — review beyond the diff
• Claude’s default under sbx is claude --dangerously-skip-permissions (agent page); FAQ frames the sandbox itself as the safety boundary for skipping approval prompts
• Host ~/.claude is not mounted; copy skills into the project (no symlinks)

---

Policy, scale, and related sandboxes

• Default allow lists can include broad wildcards (AI services, package managers, etc.) — audit with sbx policy ls
• Prefer --clone or named multi-sandbox for long / parallel / destructive work (official Claude agent page also documents sbx run --clone claude -- agents)
• Claude Code’s own /sandbox is a lighter host-side containment mode and is not the same as Docker Sandboxes microVMs (Shipyard)

---

Independent takeaways

Independent pieces frame sbx as infrastructure guardrails for YOLO (Shipyard).

They also note limits (Andrew Lock):

• signing / ssh-agent friction
• policy maintenance
• performance

YOLO becomes safer when these line up:

• microVM
• tight allow lists
• secret injection
• workspace strategy
• host-side review

---

4. Comparison: local microVM vs built-in sandbox vs hosted

Mode comparison

Mode	Boundary	Docker inside agent workflow	Typical use	Watch-outs
Docker Sandboxes (sbx)	microVM / hypervisor	Yes (in-VM daemon)	Local unattended / YOLO	Shared workspace, perf, policy
Claude Code /sandbox etc.	OS sandbox (Seatbelt/bubblewrap…)	Limited	Light containment while interactive	Still on host; thinner boundary
Host + skip-permissions	None	Host daemon	Short trusted tasks	Max contamination risk
Hosted sandbox (e.g. E2B-class)	Remote VM	Product-dependent	Shared/CI-ish	Data residency, latency, billing

---

Comparison sources

Sources: Docker security, Shipyard, Zenn hands-on (July 2026).

---

Decision heuristic

• Need local Docker for the agent → sbx
• Only light interactive containment → built-in sandbox first (sandbox chooser)
• Zero host tree sharing → --clone or remote
• Multi-agent orchestration is a different layer (e.g. Codex plugin for Claude Code)

---

5. Pricing, governance, telemetry

Pricing boundary

Official FAQ: the sbx CLI is free for commercial/professional use with no per-seat fee on a free Docker account.

Paid scope is organization governance:

• central network/FS policy
• sign-in enforcement
• audit logs

---

Telemetry and login

Telemetry covers CLI command name, success/failure, duration, username—not code/prompts—and can be disabled with SBX_NO_TELEMETRY=1.

Login is required as an identity/team/infrastructure auth anchor.

---

6. Adoption checklist

• ✓ Meet OS/hypervisor prerequisites
• ✓ Install sbx, sbx login, start on Balanced
• ✓ Run sbx policy ls and tighten allows
• ✓ Use sbx secret set or in-sandbox OAuth — no plaintext keys in the agent env
• ✓ For long/parallel/destructive work, consider --clone or named multi-sandbox
• ✓ Copy skills/hooks into the project (~/.claude not mounted; no symlinks)
• ✓ Review artifacts on the host including Git hooks
• ✓ sbx rm when finished to reclaim disk
• ✓ Decide whether org governance is required for team-wide controls

---

FAQ

Q1. Is Docker Desktop required?

No. Official get-started uses the sbx CLI alone.

---

Q2. Is Claude skip-permissions still dangerous?

On the host, yes.

Under sbx it is the documented default because the microVM is treated as the safety boundary.

You still manage:

• workspace sharing
• allow domains

FAQ mentions restoring prompts via Claude /permissions or kit entrypoint overrides.

---

Q3. Is commercial use paid?

CLI: free. Central org governance: paid.

---

Q4. Why don’t host skills load?

~/.claude is not imported. Copy skills into the project (no symlinks).

---

Q5. Why can’t the browser reach a service inside the sandbox?

In-sandbox containers are not automatically exposed on the host; use sbx ports (as shown in official/independent usage notes).

---

Summary — when to choose sbx

Pick Docker Sandboxes when you want unattended, long-running, Docker-using coding agents on a local machine without treating the host as disposable. The product value is microVM isolation plus an in-VM Docker daemon, with free CLI entry and optional paid org controls.

It is not a substitute for policy hygiene: shared workspaces, egress allows, credentials, and hook-aware review still decide residual risk. Prefer --clone or remote when you need zero host tree sharing; prefer agent-built-in sandboxes for light interactive containment.

Next step: start with one pilot project today — run sbx run claude, inspect sbx policy ls, then sbx rm.

Related articles:

• Codex Plugin for Claude Code Review and Rescue Setup
• Agentjacking Attack via Sentry MCP Hijacks Claude Code, Cursor, Codex
• Keystroke n8n Alternative for Claude Code and Cursor: Setup and Fit Check

Related new article:

• Adversarial Verification for Claude Agents: Practical Checklist – This published update adds current operational context for Docker Sandboxes (sbx) Guide: Run Claude Code Safely in a microVM.
• Role-Based Model Routing for Claude Agent Teams (2026) – This published update adds current operational context for Docker Sandboxes (sbx) Guide: Run Claude Code Safely in a microVM.