Sandboxing & Security

The Bash sandbox lets Claude run most commands without asking permission because the OS itself enforces what those commands can touch. Instead of approving each command, you define filesystem and network boundaries.

Platform: macOS (built-in Seatbelt), Linux & WSL2 (bubblewrap + socat). Native Windows is not supported — use WSL2.

Enable It

/sandbox

Panel tabs: Mode (auto-allow vs regular permissions), Overrides (allow unsandboxed fallback?), Config (resolved settings). Selection writes to .claude/settings.local.json; enable globally via ~/.claude/settings.json:

{ "sandbox": { "enabled": true } }

Linux/WSL2 setup: sudo apt-get install bubblewrap socat

The Two Modes

Mode	Behavior
Auto-allow	Sandboxed commands run without prompting. Deny rules, content ask-rules (Bash(git push *)), and dangerous rm targets still prompt
Regular permissions	Same isolation, but normal permission prompts remain

Commands that can’t run sandboxed fall back to the regular permission flow. Claude may retry a sandbox-blocked command with dangerouslyDisableSandbox — which then requires your approval. Disable that escape hatch with "allowUnsandboxedCommands": false.

What the Sandbox Enforces

Filesystem: write access only to the working directory + session temp dir by default; read access to most of the disk (credentials NOT blocked by default — see below). Applies to all child processes (npm, terraform, kubectl…).

Network: nothing pre-allowed; first use of a domain prompts, approval lasts the session. Pre-allow with settings:

{
  "sandbox": {
    "enabled": true,
    "filesystem": { "allowWrite": ["~/.kube", "/tmp/build"] },
    "network": { "allowedDomains": ["registry.npmjs.org", "*.github.com"] }
  }
}

Protect Credentials (do this!)

Default read policy still allows ~/.aws/credentials, ~/.ssh/. Lock them down:

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

"mode": "mask" (v2.1.199+) is smarter: the command sees a sentinel value, and the sandbox proxy injects the real credential only on requests to injectHosts — tools keep working, secrets never sit in logs.

Troubleshooting Quick Hits

• jest hangs → jest --no-watchman
• docker incompatible → add docker * to excludedCommands
• Go CLIs (gh/gcloud/terraform) TLS errors on macOS → excludedCommands
• WSL2 can’t call Windows binaries (cmd.exe, anything on /mnt/c/) → excludedCommands

Security Model — the Bigger Picture

Layer	Controls	Enforced by
Permission rules	Which tools run at all	Claude Code, pre-execution
Permission modes	Prompting behavior (normal/acceptEdits/plan/bypass)	Claude Code
Sandbox	What a running Bash command can touch	Operating system

They compose: sandbox holds even if a “safe-looking” command does something unexpected.

Known limits: proxy filters by hostname without TLS inspection (domain-fronting risk with broad allowlists); allowUnixSockets on docker.sock = host escape; overly broad allowWrite (e.g. to ~/.bashrc or $PATH dirs) = privilege escalation. Settings files are always write-protected from sandboxed commands.

Other isolation options: dev containers, custom containers/VMs (see docs: sandbox-environments). --dangerously-skip-permissions is blocked as root outside a recognized sandbox.

Real Case: Safe Autonomous Test-Fix Loop

Goal: let Claude run npm test / npm install freely overnight without babysitting prompts, without exposing secrets.

{
  "sandbox": {
    "enabled": true,
    "network": { "allowedDomains": ["registry.npmjs.org"] },
    "credentials": {
      "files": [{ "path": "~/.ssh", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}

Then: claude "keep running the test suite and fixing failures until green" — commands run instantly inside the boundary; anything outside it still prompts.

🧠 Quick Recall

• Trick: “Rules decide IF it runs; the sandbox decides WHAT it touches.”
• First move: deny your secrets — ~/.ssh, ~/.aws.

👨‍🏫 Teach It

• Show: /sandbox panel, then trigger a first-domain network prompt.
• They’ll trip on: native Windows isn’t supported — sandbox needs WSL2.

---

Learning path: ⬅ 15-permissions-real-examples.md · Index · ➡ 17-memory.md