Dev Containers & Sandbox Environments

When you want Claude to run fully autonomously (--dangerously-skip-permissions), you need an isolation boundary. This file compares your options — from lightest to heaviest.

The Isolation Ladder

Level	Isolation	Best for
1. Permission rules + modes	Claude Code decides pre-execution	Daily interactive work
2. Built-in Bash sandbox	OS-enforced FS/network limits on Bash	Prompt-free local automation (16)
3. sandbox-runtime wrapper	Same OS primitives wrap the whole Claude process	Stronger local guarantee
4. Dev container	Container boundary; non-root user	Unattended runs, team-standard envs
5. Custom container / VM	Full machine isolation	CI, hostile-input processing, fleets
6. Cloud (web / routines)	Anthropic-managed VMs	Zero local setup (34, 38)

Key rule: --dangerously-skip-permissions is blocked as root outside a recognized sandbox — the supported path for containers is the dev container config (runs as non-root).

Dev Containers

Anthropic ships a reference devcontainer (github.com/anthropics/claude-code → .devcontainer/): Node 20 base, firewall script that allowlists only npm registry, GitHub, and Anthropic APIs (default-deny egress), plus dev tooling (git, zsh, fzf).

VS Code flow: install the Dev Containers extension → “Reopen in Container” → run claude --dangerously-skip-permissions inside with real confidence.

// .devcontainer/devcontainer.json (essentials)
{
  "name": "Claude Code sandbox",
  "build": { "dockerfile": "Dockerfile" },
  "remoteUser": "node",
  "postCreateCommand": "sudo /usr/local/bin/init-firewall.sh"
}

Customize: extend the Dockerfile with your toolchain, adjust the firewall allowlist for your registries. The container sees only the mounted project — your SSH keys, browser profiles, and other repos stay outside.

⚠️ Even containers don’t make bypass-permissions risk-free: the container can still reach whatever domains the firewall allows, and prompt injection from files/web content remains possible. Keep the egress allowlist tight.

sandbox-runtime (@anthropic-ai/sandbox-runtime)

The same Seatbelt/bubblewrap primitives as the built-in Bash sandbox, published as a standalone wrapper — isolates the entire Claude Code process rather than just Bash commands. Useful on hosts where you can’t run Docker.

Choosing, Practically

• Solo dev, trusted repos → Level 2 (built-in sandbox, auto-allow) covers 90% of needs
• Overnight autonomous tasks → Level 4 dev container with --dangerously-skip-permissions
• CI → Level 5: fresh container per job, OIDC creds, no persistent state (35, 47)
• “Just don’t touch my machine” → Level 6: web sessions / routines run on Anthropic VMs

Real Case: Unattended Dependency Upgrade

# inside the devcontainer
claude --dangerously-skip-permissions \
  "upgrade all minor/patch deps, run the full test suite, fix what breaks,
   and prepare a commit summarizing every version bump"

Firewall means it can reach npm + GitHub only; container boundary means the worst case is a trashed workspace you rebuild in seconds.

🧠 Quick Recall

• Trick: the isolation ladder — “rules → sandbox → runtime → container → VM → cloud.”
• More autonomy ⇒ climb higher.

👨‍🏫 Teach It

• Do: quiz — match 3 scenarios (daily work, overnight run, CI) to ladder rungs.
• They’ll trip on: --dangerously-skip-permissions outside any boundary.

---

Learning path: ⬅ 52-output-styles-voice-ui.md · Index · ➡ 54-prompt-caching-deep-dive.md