Skip to content
AgentAtlas

Claude Code sandbox: /sandbox, sandbox.enabled, allowedDomains, excludedCommands and strict mode

How do I turn on and configure the Claude Code sandbox for Bash commands?

The sandbox is off by default. Run /sandbox in a session, or set sandbox.enabled to true in a settings file such as ~/.claude/settings.json. Sandboxed shell commands can write only to the working directory, a per-user temp directory and directories you added, and reach only the hosts in sandbox.network.allowedDomains, which starts empty. In auto-allow mode Claude Code runs sandboxed commands without asking.

Compare: sandbox modes in every AI coding agent →

Turn it on

In a session

/sandbox

~/.claude/settings.json

{
  "sandbox": {
    "enabled": true
  }
}
  • macOS: uses the built-in Seatbelt framework, no setup needed.
  • Linux and WSL2: needs bubblewrap and socat, for example sudo apt-get install bubblewrap socat. The /sandbox panel shows a Dependencies tab when something is missing.
  • Native Windows: commands run unsandboxed. Run Claude Code inside WSL2 to use the sandbox.

What a sandboxed command can reach

  • Writes: the working directory, a per-user temp directory and directories added with --add-dir, /add-dir or permissions.additionalDirectories. Change with sandbox.filesystem.allowWrite and denyWrite.
  • Reads: most of the machine, including ~/.ssh and ~/.aws/credentials. Block paths with sandbox.filesystem.denyRead.
  • Network: no direct route out. Traffic goes through a local proxy that checks each host against sandbox.network.allowedDomains, which starts empty. Block hosts with deniedDomains.
  • Environment variables: inherited from Claude Code, including secrets.

The sandbox covers shell commands only. Read, Edit, Write, WebFetch and WebSearch follow permission rules instead, and hooks, local MCP servers and your status line command run with your full access.

Allow write paths and network hosts

.claude/settings.json

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
  • Filesystem lists from several settings scopes are merged, not replaced.
  • Tools that read HTTP_PROXY and HTTPS_PROXY, such as curl, npm and git over HTTPS, work once their host is allowed. Plain ssh, most database drivers, UDP and ping cannot connect from the sandbox.
  • Set sandbox.network.strictAllowlist to true (in user, managed or --settings settings) to deny unlisted hosts instead of prompting.

Auto-allow mode vs regular permissions

  • Auto-allow: a command that runs inside the sandbox is approved with no prompt, even in Manual mode. Bash deny rules, content-scoped ask rules such as Bash(git push *) and rm on critical paths still apply.
  • Regular permissions: every Bash command goes through the normal permission flow, sandboxed or not.
  • autoAllowBashIfSandboxed defaults to true. Set it to false to be prompted for sandboxed commands.

Commands that leave the sandbox

Use sandbox.excludedCommands for a trusted tool that cannot work inside the sandbox. docker is incompatible with the sandbox, so the docs suggest a narrow pattern.

~/.claude/settings.json

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}
  • Patterns use Bash(...) rule syntax: docker matches only bare docker, docker * matches it with any arguments.
  • Every command in a chained call must match, so npm ci && docker compose build stays sandboxed unless npm ci is also excluded.
  • When a command fails in the sandbox, Claude may retry it with dangerouslyDisableSandbox. Manual and acceptEdits modes prompt, auto mode sends it to the classifier, dontAsk denies it and bypassPermissions runs it.
  • Linux only (Claude Code 2.1.305+): sandbox.allowNestedUserNamespaces lets sandboxed commands create user namespaces, which Chromium and rootless podman need. The changelog warns this lets them get around the sandbox's file protections, so turn it on only when you need it.

Strict sandbox mode

Set allowUnsandboxedCommands to false to turn off the unsandboxed retry. Add failIfUnavailable so Claude Code does not run commands unsandboxed when the sandbox cannot start. The /sandbox Overrides tab shows this as Strict sandbox mode.

One-off strict run

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

Some paths stay write-protected even inside allowed directories, including .claude settings files, .claude/skills, .claude/agents, .claude/hooks, .mcp.json, shell startup files, .gitconfig and hooks and config inside .git. allowWrite cannot lift this.

Sources

More Claude Code guides

Reviewed Oct 21, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →