Claude Code sandbox: what it blocks and how to turn it on
Claude Code's Bash sandbox: /sandbox and auto-allow, its default write, read and network limits, bubblewrap and the Ubuntu AppArmor fix, and its limits.
Claude Code’s sandbox is an operating-system boundary around the shell commands Claude runs and the processes they start: Seatbelt on macOS, bubblewrap on Linux and WSL2. It is off by default. Type /sandbox and choose auto-allow to let sandboxed commands run without a prompt, or regular permissions to keep the prompts and add the boundary. Once on, commands can write only to the project, a temp folder and directories you added; they can read almost everything, credential files included; and their network goes through a proxy whose list of allowed hosts starts empty. On Ubuntu, install bubblewrap and socat first. It does not cover Claude’s file-edit tools, WebFetch, MCP servers or hooks.
What it covers, and what it does not
Anthropic’s sandboxing page is precise about the scope: the boundary wraps the Bash, PowerShell and Monitor tools and every child process they start, so npm test, a build script or a curl inside them is boxed. Everything else in a session runs with your full access:
- The built-in file and web tools (Read, Edit, Write, WebFetch, WebSearch) follow permission rules instead. “A
denyReadentry doesn’t stop the Read tool, andallowedDomainsdoesn’t limit WebFetch.” - Other processes Claude Code starts: command hooks, local MCP servers, plugin monitors, LSP servers, your status line command and
apiKeyHelper. - Mods, and anything a mod starts.
Subagents use the parent session’s sandbox settings. On native Windows nothing is sandboxed; use WSL2. On WSL1 Claude Code says Sandboxing needs WSL2 or Sandboxing requires WSL2.
Turning it on
Type /sandbox in a session. The panel has three tabs: Mode (auto-allow or regular permissions), Overrides (whether a command that fails in the sandbox may be retried outside it) and Config (the settings in effect), plus a Dependencies tab on Linux when something is missing. Your choice is saved to .claude/settings.local.json in the current project, so it applies to that project only. To sandbox every project, put the keys in ~/.claude/settings.json:
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true
}
}CopiedBoth keys matter. "enabled": true alone gives you regular permissions mode: the boundary, with every command still prompting. Auto-allow used to be the default; since Claude Code 2.1.325, per Anthropic’s changelog, sandboxed Bash commands follow the normal permission flow unless autoAllowBashIfSandboxed is true. A config written for an older version that relied on the old default now prompts again.
If /sandbox prints Sandbox settings can’t be changed here, a higher level (managed settings, or a --settings file you started with) already sets one of these keys; the Setting sources line in /status shows which.
What a sandboxed command can do by default
- Write: the working directory, a per-user temp directory, and directories added with
--add-dir,/add-dirorpermissions.additionalDirectories. More paths go insandbox.filesystem.allowWrite. A write anywhere else fails withRead-only file systemon Linux and WSL2, orOperation not permittedon macOS. - Read: nearly the whole machine, including
~/.sshand~/.aws/credentials.sandbox.filesystem.denyRead, or acredentialsentry with"mode": "deny"(which also works for environment variables such asGITHUB_TOKEN), closes what you name. - Network: no direct route out. Traffic goes through Claude Code’s proxy, which checks each host against
sandbox.network.allowedDomains, empty to begin with. Entries take wildcards such as*.example.comand an optional:port;deniedDomainsblocks a host in every mode.
What happens at a host that is not on the list depends on the permission mode, not on the sandbox mode:
| Permission mode | A host not in allowedDomains |
|---|---|
Manual, acceptEdits | You get a prompt |
Auto mode | Refused, unless the command listed the host and the classifier approved it |
dontAsk | Refused |
bypassPermissions | Allowed without a prompt |
Tools that ignore the proxy environment variables cannot connect at all, even to an allowed host: Anthropic names plain ssh, most database drivers, and anything using UDP. A git push to an SSH remote runs plain ssh, so expect it to fail inside the box (an inference from that list, not a case the docs spell out).
Auto-allow and regular permissions
In auto-allow, “Claude Code approves a command automatically, with no prompt, when the command runs inside the sandbox”, whatever your permission mode (plan mode and two auto-mode cases aside), so you get prompt-free shell work even outside acceptEdits. Three things still stop a sandboxed command: a Bash deny rule that matches it, rm or rmdir aimed at a critical path, and a content-scoped ask rule such as Bash(git push *). A command that cannot run in the sandbox goes through the normal prompts. In regular permissions mode every Bash command is asked about, sandboxed or not; the sandbox only limits what an approved command can reach. How this sits beside auto mode and --dangerously-skip-permissions is in running Claude Code and Codex without permission prompts.
Linux and WSL2: bubblewrap and socat
bubblewrap does the filesystem isolation and socat relays network traffic to the proxy. On Ubuntu or Debian:
sudo apt-get install bubblewrap socatCopiedOn Fedora, sudo dnf install bubblewrap socat. The check runs at startup, so restart Claude Code afterwards. If /sandbox shows only a Dependencies tab, the sandbox cannot start and the tab says what is missing. If Dependencies sits beside the other tabs, only something optional is missing, usually the seccomp filter, which adds blocking of Unix domain sockets; Anthropic’s install for it is npm install -g @anthropic-ai/sandbox-runtime. ripgrep, also on the list, comes bundled with the native install.
Ubuntu 24.04: the AppArmor restriction on user namespaces
bubblewrap creates unprivileged user namespaces, and Ubuntu 23.10 and 24.04 LTS introduced an AppArmor restriction on exactly that. Check whether it is on:
sysctl kernel.apparmor_restrict_unprivileged_usernsCopied= 1 means it is on, and Claude Code then reports:
Ubuntu's AppArmor restriction on user namespaces stops bubblewrap hereCopiedSandboxed commands may instead fail with bwrap: setting up uid map: Permission denied or a Failed RTM_NEWADDR error. Until you fix it, commands run unsandboxed under the normal prompts. Anthropic’s fix, for the usual case where which bwrap prints /usr/bin/bwrap, is an AppArmor profile for it, applied by reloading AppArmor:
sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>
profile bwrap /usr/bin/bwrap flags=(unconfined) {
userns,
include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmorCopiedThen restart Claude Code. If the first bwrap on your PATH is somewhere else, the documented alternative lifts the restriction for every program on the machine until the next reboot:
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0CopiedCodex’s sandbox is bubblewrap too and fails the same way; its messages are in Codex’s bubblewrap errors.
Inside a Docker container, bubblewrap cannot mount a fresh /proc and fails with Can’t mount proc on /newroot/proc: Operation not permitted. sandbox.enableWeakerNestedSandbox: true gets it running, and Anthropic says it “considerably weakens security”: use it only when the container is already the boundary you rely on.
Check that it is working
Ask Claude to run these two commands. Both should fail:
touch ~/sandbox-probe
curl --noproxy '*' https://example.comCopiedThe first with Read-only file system (Linux, WSL2) or Operation not permitted (macOS), the second with Could not resolve host. If the file appears, the sandbox is not running, and by default Claude Code does not stop you: “when the platform doesn’t support the sandbox or the dependency check at startup fails, Claude Code runs commands without sandboxing.” Set sandbox.failIfUnavailable to true so it refuses to start instead; a sandbox that then breaks mid-session refuses each command with Sandbox is required but failed to initialize and the reason. On a server you reach over SSH, where nobody is watching the startup screen, that is the setting to add.
The ways out: excluded commands and the unsandboxed retry
Excluded commands. Some tools cannot work in the box; Anthropic’s own example is that “docker is incompatible with the sandbox”. sandbox.excludedCommands runs matching commands outside it with full access, using the same patterns as a Bash(...) rule:
{
"sandbox": {
"enabled": true,
"excludedCommands": ["docker compose *"]
}
}CopiedAn entry only frees a call it fully covers: docker * does not take npm ci && docker build . out of the sandbox. Keep the patterns narrow.
The unsandboxed retry. When the sandbox blocks a command, Claude “may retry the command with the dangerouslyDisableSandbox parameter”, and the retry runs unsandboxed. In manual and acceptEdits mode you see a prompt titled “Bash command (unsandboxed)”; in auto mode the classifier decides; in dontAsk it is denied; in bypassPermissions it runs without asking. To remove the retry entirely, which the Overrides tab calls strict sandbox mode:
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false
}
}CopiedThe limits Anthropic states
“Sandboxing reduces risk but is not a complete isolation boundary,” in the docs’ own words. The points to weigh:
- The proxy filters by hostname and does not inspect TLS, so an allowed broad domain such as
github.com“can create paths for data exfiltration”. - Allowed Unix sockets can undo it: allowing
/var/run/docker.sock“effectively grants access to the host system”. - Wide write grants can undo it: writable folders on
PATH, system config or.bashrclet code run later outside the box. - It is not enough for unattended runs. Anthropic’s sandbox environments page says the Bash sandbox “is not sufficient for fully unattended runs”, because the file tools, MCP servers and hooks sit outside it. For those, it points at a container, a VM, or the sandbox runtime below.
Hooks run unsandboxed with your full access, which matters if you write them yourself; see Claude Code hooks.
The sandbox runtime: the same box around all of Claude Code
The sandbox is built on Anthropic’s open-source sandbox-runtime package, “a lightweight sandboxing tool for enforcing filesystem and network restrictions on arbitrary processes at the OS level, without requiring a container.” Its command, srt, can wrap the whole Claude Code process, so the file tools, MCP servers and hooks are inside the boundary as well. Anthropic calls it a beta research preview whose configuration format may change.
npm install -g @anthropic-ai/sandbox-runtime
srt claudeCopiedIt reads ~/.srt-settings.json (or a file passed with --settings), and with no settings file it still starts, with no network and writes confined to its own paths, so a clean start is not proof your settings loaded. For Claude Code to work inside it, the docs list write access to the project, ~/.claude, ~/.claude.json and /tmp on Linux, and the domains api.anthropic.com, plus claude.ai and platform.claude.com if you sign in with a Claude account rather than an API key. On Linux it also wants ripgrep from your package manager.
On a server, the machine itself can be the outer boundary: what a sandboxed or unsandboxed agent can reach is what the machine holds. Setting one up for Claude Code is in Claude Code on Linux, and locking the server down in securing a VPS for Claude Code and Codex. As of November 2026, Claude Code’s newest release is 2.1.330.