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

Sandboxing cover

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:

Terminal
# Ubuntu/Debian
sudo apt-get install bubblewrap socat
# Fedora
sudo dnf install bubblewrap socat

macOS needs nothing extra. Restart Claude Code after installing, then run:

/sandbox

The 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:

Terminal
touch ~/sandbox-probe
curl --noproxy '*' https://example.com

The 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 Bash deny rule
  • rm or rmdir on critical paths
  • Content-scoped ask rules, such as Bash(git push *)
  • Commands like FOO=bar npm test or eval "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:

JSON
{
  "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:

Terminal
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.254 metadata endpoint, unless you list the IP.
  • Excluded commands are fully unsandboxed. Anything in excludedCommands has 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.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides