How to Sandbox Claude Code in 2026: Filesystem and Network Isolation, Step by Step

The Claude Code sandbox is a boundary the operating system enforces around the shell commands Claude runs, limiting which files and network hosts those commands can reach. You turn it on with /sandbox or by setting sandbox.enabled to true in a settings file, and once it is on Claude Code can run sandboxed commands without stopping to ask you to approve each one. That is the real draw: fewer permission prompts without handing an autonomous agent an open shell on your laptop.

This guide covers what the sandbox actually restricts, how to enable it on macOS, Linux, and WSL2, the two approval modes, and the parts that run outside the boundary — the gap that turned into a real data-exfiltration bug earlier this year. We run Claude Code in headless automation to publish this site, so getting the shell boundary right is not academic for us.

What is the Claude Code sandbox?

The sandbox is built into Claude Code and wraps every Bash, PowerShell, and Monitor command plus the child processes those commands spawn. It draws two boundaries at once: what a command can touch on disk, and what it can reach over the network. Both are enforced by the OS while the command runs, which is why a sandboxed command can be auto-approved — the kernel, not a prompt, is holding the line.

It is off by default. On macOS it uses the built-in Seatbelt framework, so there is nothing to install. On Linux and WSL2 it relies on bubblewrap for filesystem isolation and socat to relay network traffic through a local proxy; the /sandbox panel tells you if either is missing. On native Windows there is no sandbox at all — commands run unsandboxed unless you run Claude Code inside a WSL2 distribution. Under the hood it is the open-source @anthropic-ai/sandbox-runtime package.

How filesystem and network isolation work

The two boundaries have different defaults, and you widen or narrow each one independently. The table below is the starting state and the settings that change it.

Access	Default behavior	Change it with
Writes	Working directory, a per-user temp dir, and any directories you added with --add-dir. Protected paths stay write-denied	filesystem.allowWrite, filesystem.denyWrite
Reads	Most of the machine — including credential files like ~/.ssh and ~/.aws/credentials	filesystem.denyRead, credentials
Network	No direct route out; every connection goes through a local proxy that checks the host against your allowed domains, which start empty	network.allowedDomains, network.deniedDomains

The asymmetry worth internalizing: writes are locked down by default, but reads are wide open. A sandboxed command cannot scribble outside your project, yet it can still read your SSH keys and cloud credentials unless you add a denyRead rule or use the credentials protection. The network side is the opposite — deny-by-default, with an allowlist you build up as commands need specific hosts.

How to turn on the Claude Code sandbox

The fastest path is interactive:

• Run /sandbox in a session. The panel has a Mode tab, an Overrides tab (the allowUnsandboxedCommands fallback), and a Config tab showing the resolved settings. On Linux a Dependencies tab appears if bubblewrap, socat, or ripgrep is missing.
• Pick a mode (covered below) and ask Claude to run a build or test suite. Selecting a mode writes it to the project's .claude/settings.local.json.
• Enable it everywhere by setting sandbox.enabled to true in ~/.claude/settings.json, or enforce it for a whole team with managed settings.

For a single session without touching a settings file, pass it on the CLI:

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

To verify it is live, ask Claude to run touch ~/sandbox-probe (should fail with Operation not permitted or Read-only file system) and curl --noproxy '*' https://example.com (should fail with Could not resolve host). If you need the agent to hard-stop when the sandbox can't start — rather than silently falling back to unsandboxed — set sandbox.failIfUnavailable to true. That setting is the difference between "sandbox is a convenience" and "sandbox is a security gate."

Sandbox modes: auto-allow vs regular permissions

Both modes enforce the identical filesystem and network limits. The only difference is approval.

• Auto-allow mode runs sandboxed commands with no prompt. This is where the prompt-fatigue payoff lives: a command that only writes inside the boundary just runs, even in manual mode. Deny rules are still respected, rm against a critical path still prompts, and content-scoped ask rules like Bash(git push *) still force a prompt.
• Regular permissions mode sends every Bash command through the normal permission flow even when sandboxed — more control, more clicks.

The first time a command needs a new network domain, Claude Code prompts you to add it to the allowlist. In auto mode the model instead declares the hosts a command needs on the command itself, and a server-side classifier reviews them. Note that plan mode does not inherit auto-allow — it keeps gating commands while you plan.

What runs outside the sandbox (the part people miss)

The sandbox wraps shell commands. It does not wrap everything, and this is the single most misunderstood thing about it. Running outside the boundary:

• Built-in file and web tools — Read, Edit, Write, WebFetch, WebSearch follow permission rules instead. A denyRead entry does not stop the Read tool, and allowedDomains does not limit WebFetch.
• MCP servers and hooks — both run unsandboxed.
• Commands you type at the ! shell prompt, anything matching excludedCommands, and any unsandboxed retry, where Claude re-runs a failed command with dangerouslyDisableSandbox.

So a denyRead on ~/.aws/credentials blocks a sandboxed cat, but not the Read tool or an MCP server reaching the same file. If you want one boundary around all of that, the sandbox is the wrong layer — run the whole Claude Code process inside a container or VM. This matters most when you run Claude Code headless in CI, where there is no human to decline an unsandboxed retry.

A sandbox is not a jail: the egress-bypass lesson

Treat the network allowlist as defense-in-depth, not a vault. Security researchers disclosed a sandbox network-egress bypass in Claude Code affecting versions 2.0.24 through 2.1.89 — roughly 130 releases — where a SOCKS5 null-byte hostname trick let commands reach blocked domains and exfiltrate API keys, tokens, and source. A crafted hostname like attacker.com\x00.google.com passed the JavaScript allowlist check (it saw the .google.com suffix) while the OS resolver truncated at the null byte and connected to the attacker. Anthropic shipped stricter hostname validation in v2.1.90 on April 1, 2026, reportedly without a CVE or changelog note.

The practical takeaways: keep Claude Code updated, keep allowedDomains as short as the task allows, set sandbox.failIfUnavailable where the sandbox is a real control, and for anything handling production secrets, isolate the whole process — not just its shell. The sandbox meaningfully raises the cost of a mistake or a prompt-injection, but it is one layer, and layers have had holes.

FAQ

Is the Claude Code sandbox on by default? No. It is off until you run /sandbox or set sandbox.enabled to true in a settings file. On native Windows it does not run at all unless you use WSL2.

Does the sandbox stop Claude from reading my credentials? Not by default. Sandboxed commands can read most of the machine, including ~/.ssh and ~/.aws/credentials. Add a filesystem.denyRead rule or use the credentials protection, and remember the Read tool and MCP servers are outside the sandbox entirely.

What do I need to install on Linux? bubblewrap and socat are required; ripgrep ships with the native binary, and an optional seccomp filter (from @anthropic-ai/sandbox-runtime) adds Unix-socket blocking. The /sandbox Dependencies tab lists what is missing.

Will the sandbox reduce permission prompts? Yes, in auto-allow mode — sandboxed commands run without asking, because the OS is enforcing the boundary. Deny rules, critical-path rm, and content-scoped ask rules still prompt.

Is the sandbox enough to run an agent safely on production data? Treat it as one layer. It restricts shell commands but not file tools, MCP servers, or hooks, and it has had at least one egress-bypass bug. For production secrets, run the whole process in a container or VM.

Sources

• Claude Code docs — Configure the sandboxed Bash tool: what the sandbox restricts, settings keys, modes, dependencies, and what runs outside it.
• GBHackers — Claude Code sandbox flaw may compromise user secrets: the SOCKS5 null-byte egress bypass, affected versions 2.0.24–2.1.89, and the v2.1.90 fix.
• anthropics/sandbox-runtime (GitHub): the open-source package the built-in sandbox is built on.