Claude Code Sandboxing: What It Blocks and How to Enable It
Claude Code sandboxing puts an OS boundary around Claude's shell commands. What it blocks, /sandbox setup, OS support, settings keys and fewer prompts.
Josh Pocock7 min read
AI Coding
Sandboxing
Stride AI Academy
Claude Code sandboxing puts an operating system boundary around the shell commands Claude runs. Writes are limited to your project and a temp folder, and network traffic only reaches domains you allow. It's off by default. Turn it on with /sandbox in a session, and in auto-allow mode sandboxed commands run without a permission prompt.
This guide covers what the sandbox blocks and what it doesn't, OS support, setup, the settings keys, how it cuts permission prompts, and when to use a dev container instead. Everything here was checked against Claude Code's sandboxing docs, the sandbox environments comparison and the guidance on getting good results on November 22, 2026.
What the Claude Code sandbox blocks
The sandbox wraps Bash, PowerShell and Monitor tool commands, plus any processes they start. With it on, the docs describe this default boundary:
| Area | Default |
|---|---|
| Writes | Allowed in the working directory, a per-user temp folder and any added directories |
| Protected files | Write-denied even inside writable folders: .claude/settings*, .mcp.json, .bashrc, .gitconfig, .git/hooks, ~/.claude and similar |
| Reads | Allowed across most of the machine, including ~/.ssh and ~/.aws/credentials, unless you restrict them |
| Network | No direct route out. A local proxy checks each host against allowedDomains, which starts empty |
| Environment variables | Inherited from Claude Code, secrets included |
Two of those rows surprise people. Reads are open by default, and environment variables come through. If you care about credentials, restrict them with the settings below.
It's built on the open-source @anthropic-ai/sandbox-runtime package.
What runs outside the sandbox
The sandbox covers shell commands only. The docs list these as running outside it:
- Built-in file and web tools: Read, Edit, Write, WebFetch and WebSearch
- Command hooks, local MCP servers and LSP servers
- Status line commands and
apiKeyHelper - Commands you type yourself at the
!prompt, usually
Built-in tools are gated by permission rules instead. Anthropic's guidance page notes the sandbox picks up your Read deny rules and WebFetch(domain:...) rules too, and that for anything security-related you want both.
Which operating systems support sandboxing
| Platform | Mechanism |
|---|---|
| macOS | Seatbelt, built in |
| Linux | bubblewrap |
| WSL2 | bubblewrap (WSL1 doesn't work) |
| Native Windows | Not supported. Commands run unsandboxed |
On Windows, run Claude Code inside WSL2, or use a container or VM. Our Claude Code on Windows guide covers the WSL setup.
How to turn on sandbox mode
On Linux and WSL2, install the two packages first:
# Ubuntu/Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socatmacOS needs nothing extra. Restart Claude Code after installing, then run:
/sandboxThe panel has Mode, Overrides and Config tabs, plus a Dependencies tab if something is missing. Pick a mode:
- Auto-allow: sandboxed commands run without a permission prompt.
- Regular permissions: every Bash command still goes through the normal permission flow, even inside the sandbox.
To check it works, the docs suggest asking Claude to run these two commands. Both should fail:
touch ~/sandbox-probe
curl --noproxy '*' https://example.comThe first should fail with Operation not permitted on macOS or Read-only file system on Linux and WSL2. The second should fail with Could not resolve host.
How sandboxing cuts permission prompts
In auto-allow mode, the sandbox is the boundary instead of you. Commands inside it run without asking. Some still prompt or get blocked:
- Commands that match a
Bashdeny rule rmorrmdiron critical paths- Content-scoped ask rules, such as
Bash(git push *) - Commands like
FOO=bar npm testoreval "ls", which go through the regular flow
This is the main reason to turn it on. If you've been reaching for --dangerously-skip-permissions to stop the prompts, sandboxing plus auto-allow gets you most of the way with a real boundary. Our guide to dangerously skip permissions covers the trade-offs.
Claude Code sandbox settings
You can set everything in ~/.claude/settings.json (all projects), .claude/settings.json (one project) or managed settings (your organization). This example from the docs locks down reads, adds two write paths, allows two domains and blocks credentials:
{
"sandbox": {
"enabled": true,
"filesystem": {
"allowWrite": ["~/.kube", "/tmp/build"],
"denyRead": ["~/"],
"allowRead": ["."]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"]
},
"excludedCommands": ["docker compose *"],
"credentials": {
"files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
"envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
}
}
}The keys you'll use most:
| Key | What it does |
|---|---|
sandbox.enabled |
Turns the sandbox on |
sandbox.filesystem.allowWrite, denyWrite, denyRead, allowRead |
Path rules. /tmp/build is absolute and ~/.kube is home-relative |
sandbox.network.allowedDomains, deniedDomains |
Host allow and deny lists |
sandbox.excludedCommands |
Runs matching commands fully outside the sandbox. Use sparingly |
sandbox.allowUnsandboxedCommands |
Set to false to turn off the retry escape hatch |
sandbox.failIfUnavailable |
Set to true to exit at startup instead of running unsandboxed |
sandbox.credentials |
deny blocks reads and removes env vars |
One detail trips people up: sandbox paths use normal conventions, but Read and Edit permission rules use //path for absolute paths. Our settings.json guide explains how the files combine.
The escape hatch, and strict mode
When a command fails inside the sandbox, Claude may retry it with dangerouslyDisableSandbox. What happens next depends on your permission mode: a prompt in manual and acceptEdits, the classifier in auto mode, denial in dontAsk, and no prompt in bypassPermissions.
To close the hatch, set allowUnsandboxedCommands to false, or use strict sandbox mode in the /sandbox Overrides tab. You can try a locked-down session from the CLI:
claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'Limits to know
- Proxy-unaware tools fail.
ssh, most database drivers and UDP tools can't reach hosts, even allowed ones.docker, Chromium and rootless Podman also fail inside the sandbox. - No TLS inspection by default. The proxy checks hostnames, not traffic, unless you set
network.tlsTerminate. - Local addresses are refused, including the
169.254.169.254metadata endpoint, unless you list the IP. - Excluded commands are fully unsandboxed. Anything in
excludedCommandshas no filesystem or network limits.
The sandbox environments page adds a warning worth repeating: isolation reduces the damage of a mistake but doesn't remove risk. Anything with network access can still leak what it can read, and a writable project folder can still be changed.
Sandbox vs dev container
The built-in sandbox only covers shell commands. The docs compare it with heavier options:
| Approach | What's isolated | Needs Docker |
|---|---|---|
| Sandboxed Bash tool | Bash, PowerShell and Monitor commands | No |
Sandbox runtime (srt claude) |
The whole Claude Code process, including file tools, MCP servers and hooks | No |
| Dev container | The full development environment | Yes |
| Virtual machine | A full operating system | No |
| Cloud session | Shell commands and edits in an Anthropic-managed VM | No |
The docs' rule of thumb: use the sandbox in auto-allow mode to cut prompts during everyday work on your own machine. For unattended runs with --dangerously-skip-permissions, use a dev container, another container or VM, or the sandbox runtime, so file tools, MCP servers and hooks are inside the boundary too. The sandbox runtime is a beta research preview. Cloud sessions are covered in our Claude Code on the web guide.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
Does Claude Code have a sandbox?
Yes. It's a built-in, OS-enforced sandbox for the shell commands Claude runs, built on Anthropic's open-source sandbox runtime. It's off by default. Run /sandbox to turn it on.
How do I turn on Claude Code sandbox mode?
Run /sandbox in a session and choose a mode on the Mode tab. On Linux and WSL2, install bubblewrap and socat first. In a settings file, set sandbox.enabled to true.
Does Claude Code sandboxing work on Windows?
Not natively. On November 22, 2026 the docs list macOS, Linux and WSL2 only. On native Windows, commands run unsandboxed, so use WSL2 or a container.
Does the sandbox stop Claude reading my files?
Not by default. Reads are allowed across most of the machine, including ~/.ssh. Add denyRead paths or sandbox.credentials entries, and keep Read deny rules in your permissions for the built-in Read tool.
Is sandboxing safer than --dangerously-skip-permissions?
They do different jobs. Bypass mode removes prompts, and the sandbox limits what commands can reach. The docs say the sandbox alone isn't enough for fully unattended runs, because file tools, MCP servers and hooks run outside it.
Does the sandbox cover MCP servers and hooks?
No. Local MCP servers, command hooks and LSP servers run outside it. To put them inside one boundary, run Claude Code through the sandbox runtime with srt claude, or inside a dev container or VM.