What Is Sandbox Mode in Claude Code?

What Is Sandbox Mode in Claude Code?

There are two ways to stop an agent doing something you did not want.

You can ask it to check with you first, or you can make the thing impossible.

Permission prompts are the first kind. They work until the twentieth prompt of the afternoon, at which point you are approving on reflex and the protection has quietly become theatre.

Claude Code's sandbox is the second kind, and that difference is the whole point of it.

It is worth understanding precisely, because it is strong where people assume it is weak and — much more importantly — it is narrow where people assume it is total.

The Short Answer

The sandbox is a boundary the operating system enforces around the shell commands Claude runs on your machine.

You decide which files and which network domains those commands can reach, and the limits apply to Bash, PowerShell and Monitor commands and to every process they start.

Because the operating system applies those limits while the command runs, Claude Code does not need to ask you to approve each one.

That is the trade: you spend a few minutes configuring boundaries once, instead of answering prompts all day.

Two things to fix in your mind immediately. It is off by default.

And it covers shell commands only — the documentation is blunt that Claude's file tools, MCP servers and hooks run outside it.

Automation only pays off when what it produces is sound. Get a free SEO audit and see what your own measurement is really telling you.

What the Sandbox Actually Limits

The boundary has four dimensions, and the defaults are not symmetrical. Writes and network are tight out of the box. Reads are not.

Writes are restricted by default

A sandboxed command can write to the working directory, a per-user temporary directory, and any directories you have added yourself. Protected paths stay write-denied.

You widen or narrow that with filesystem.allowWrite and filesystem.denyWrite.

Reads are wide open by default, and this is the one to notice

The default read scope is most of the machine — and the documentation names the consequence explicitly, including credential files such as ~/.ssh and ~/.aws/credentials.

That is not a loophole, it is the stated default, and it is the single most important thing to configure before you trust the sandbox with anything sensitive. The tools for it are filesystem.denyRead and the credentials settings.

Network egress is denied by default

There is no direct route out of the sandbox. Connections go through a proxy running on your own machine, which checks each host against your list of allowed domains — and that list starts empty.

You open it up with network.allowedDomains and close specific holes with network.deniedDomains.

Starting from nothing is the right default and it is the opposite of how most people assume a dev tool behaves.

Environment variables are inherited

Sandboxed commands inherit the environment from Claude Code, secrets included. You manage that with the credentials settings and the CLAUDE_CODE_SUBPROCESS_ENV_SCRUB variable.

How to Turn It On, Step by Step

Step 1: open the sandbox panel. Run /sandbox. It opens a panel with tabs for Mode, Overrides and Config. On Linux you may also see a Dependencies tab when an optional seccomp filter is missing.

Step 2: choose a mode. The Mode tab offers auto-allow or regular permissions. Under auto-allow, a command that runs inside the sandbox is approved automatically with no prompt. Under regular permissions, every Bash command still goes through the normal permission flow even when sandboxed.

Step 3: decide whether unsandboxed commands are allowed at all. The Overrides tab exposes allowUnsandboxedCommands, labelled "Strict sandbox mode". Setting it to false is what makes the boundary meaningful rather than advisory.

Step 4: write the settings down. The keys live in a sandbox block. The essentials are sandbox.enabled, the sandbox.filesystem allow and deny lists, and sandbox.network.allowedDomains.

Step 5: pick the right file for the job. User settings go in ~/.claude/settings.json. Project-shared settings go in .claude/settings.json, project-local in .claude/settings.local.json — and the mode you pick in /sandbox is saved to the local one. For a single session you can pass settings inline with --settings.

Step 6: add the belt-and-braces keys for unattended work. sandbox.failIfUnavailable set to true stops a session running at all if the sandbox cannot start, which is what you want rather than a silent downgrade. sandbox.autoAllowBashIfSandboxed defaults to true.

Step 7: verify it is really on. Do not take the panel's word for it. touch ~/sandbox-probe should fail with "Operation not permitted" on macOS, or "Read-only file system" on Linux and WSL2. curl --noproxy '*' https://example.com should fail with "Could not resolve host."

Those two probes take five seconds and they are the difference between a sandbox and the belief that you have one.

Guesswork is expensive in security and in search alike. Get a free SEO audit and replace assumptions with numbers.

The scope rule that matters most

Some sandbox settings are deliberately not honoured from project files, and the reasoning is worth internalising.

sandbox.filesystem.disabled is read only from user settings, managed settings, and --settings. Project settings cannot set it — the documentation's point is that a checked-out project should not be able to switch filesystem isolation off. The key requires v2.1.216 or later.

The same logic applies to excludedCommands: where the sandbox is admin-required, entries in .claude/settings.json and .claude/settings.local.json are ignored. Repository files cannot loosen the boundary.

If you have ever cloned a repository you had not read line by line, you will see why this exists.

When the Sandbox Is the Right Tool

Long unattended runs. This is the strongest case. A migration across hundreds of files or an overnight batch job cannot stop to ask permission, and auto-allow inside a boundary is a far better answer than turning prompts off and hoping.

Untrusted or unfamiliar code. A repository you did not write, a dependency you have not audited, generated code you have not read yet.

Prompt-fatigue relief on ordinary work. If you are approving the same safe commands twenty times a day, a sandbox converts that into a one-time configuration.

Shared or team setups, where managed settings can enforce a floor that project files cannot undercut.

Boundaries beat good intentions, in security and in search. Get a free SEO audit and find the gaps before they cost you.

Limitations and What It Does Not Cover

This section matters more than the rest of the article, because every real failure here comes from assuming the boundary is wider than it is.

Built-in file and web tools are outside it. Read, Edit, Write, WebFetch and WebSearch follow permission rules instead. A denyRead entry does not stop the Read tool, and allowedDomains does not limit WebFetch. If your mental model is "the sandbox contains Claude", it is wrong — it contains Claude's shell.

Several things run with your full access: command hooks, local MCP servers, plugin monitors, LSP servers, and helper commands such as your status line command and apiKeyHelper.

Some shell commands escape by design. Commands typed at the ! shell-mode prompt run unsandboxed in most sessions. Commands matching excludedCommands run with your full access — and a broad entry such as docker * covers everything that tool can do. Claude can also ask to run a command unsandboxed, usually after it has failed inside the sandbox.

An excluded interpreter is an open door. If a pattern covers an interpreter or a script inside the working directory, Claude can write that file and then run it outside the sandbox. Exclusion patterns deserve the same suspicion as a deny-list bypass.

Turning filesystem isolation off has a compounding failure mode. The documentation spells it out: a sandboxed command can write files that later commands run or read — shell startup files, executables on $PATH, ~/.claude/settings.json — and use them to widen its own access on the next run.

Isolation reduces blast radius, it does not remove risk. Any setup that allows network egress can still leak data the agent can read, and any setup that mounts your project directory writable can still modify that code.

Platform support is not universal. The sandbox runs on macOS, Linux and WSL2. On native Windows, Claude Code runs commands unsandboxed — to sandbox on a Windows machine you run Claude Code inside a WSL2 distribution. WSL1 reports "Sandboxing requires WSL2." macOS uses the built-in Seatbelt framework; Linux and WSL2 use bubblewrap and socat.

On Linux the deny list is built once at launch. It does not cover anything the session creates later, such as a git init, a git clone, or scaffolding generated mid-run.

On Ubuntu 24.04 and later, AppArmor can block bubblewrap's user namespaces. The documentation provides a profile fix followed by sudo systemctl reload apparmor.

The underlying runtime is a beta research preview and its configuration format may change as the package evolves. That is a caveat, not a deprecation — and the feature is plainly under active development, with behaviour changes landing as recently as v2.1.285.

Sandbox vs the Other Ways to Contain Claude Code

Sandbox vs permission prompts. Not alternatives — they answer different questions. Prompts ask whether an action is wanted; the sandbox decides whether it is possible. Prompts degrade with fatigue; an OS boundary does not get tired. Use the sandbox for the floor and prompts for judgement calls on top.

Sandbox vs auto mode's classifier. The documentation's phrasing is the clearest statement of the distinction available: the classifier is a per-action control, not an isolation boundary. A classifier forms a view about a command. The sandbox makes the command unable to do the thing regardless of anyone's view.

Sandbox vs --dangerously-skip-permissions. These belong together rather than in competition. The guidance is to run skip-permissions sessions inside a container, a VM or the sandbox runtime, precisely so that file tools, MCP servers and hooks fall inside a boundary too. On Linux and macOS, Claude Code refuses to start with that flag as root.

Sandbox vs a container or VM. The honest comparison. The built-in sandbox covers shell commands; a container covers the whole process. The documentation's own conclusion is that the sandboxed Bash tool on its own constrains only shell commands, so it is not sufficient for fully unattended runs in either mode. For genuinely unsupervised work, the container is the boundary and the sandbox is a second layer inside it.

Know what your stack is actually doing. Get a free SEO audit and get a clear read on your site's performance.

Final Thoughts

The sandbox is the most useful safety feature in Claude Code and the easiest one to misread.

Get the model right and everything else follows: the operating system constrains the shell, and nothing else.

So the practical sequence is short. Turn it on. Close down the read defaults, because wide-open reads including credential files is where the real exposure sits. Start from an empty allowed-domains list and add only what you need.

Set allowUnsandboxedCommands to false if you want the boundary to mean anything. Run the two verification probes. And if the work is genuinely unattended, put the whole thing inside a container as well.

For the other half of this picture — what happens when you switch the prompts off entirely, and what Claude Code still refuses to do even then — see our guide to what dangerously-skip-permissions does in Claude Code.