GuidesSecurity

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.

November 21, 2026The Everpod team
The short answer

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:

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
  }
}
Copied

Both 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

What happens at a host that is not on the list depends on the permission mode, not on the sandbox mode:

Permission modeA 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 socat
Copied

On 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_userns
Copied

= 1 means it is on, and Claude Code then reports:

Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here
Copied

Sandboxed 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 apparmor
Copied

Then 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=0
Copied

Codex’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.com
Copied

The 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 *"]
  }
}
Copied

An 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
  }
}
Copied

The limits Anthropic states

“Sandboxing reduces risk but is not a complete isolation boundary,” in the docs’ own words. The points to weigh:

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 claude
Copied

It 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.

Run Claude Code on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.