The Claude Code sandbox, in plain words

The sandbox is a boundary that your operating system enforces around the shell commands Claude runs. You decide which files and network domains those commands can reach. Because the operating system applies the limits while a command runs, Claude Code can run sandboxed commands without asking you to approve each one. It is off by default.

What it covers, and what it does not

The sandbox wraps shell commands (Bash, PowerShell and Monitor commands) and the processes they start. Everything else follows other rules:

• The built-in file and web tools (Read, Edit, Write, WebFetch, WebSearch) follow permission rules, not the sandbox. A sandbox read restriction does not stop the Read tool.
• Hooks, local MCP servers, LSP servers and helper commands such as your status line command run with your full access.
• Commands you type yourself at the ! shell prompt usually run unsandboxed.

It runs on macOS, Linux and WSL2. On native Windows, Claude Code runs commands unsandboxed; the docs say to use WSL2 if you want the sandbox on a Windows machine. On Linux and WSL2 it needs two packages, bubblewrap and socat, for example sudo apt-get install bubblewrap socat on Ubuntu or Debian.

Turn it on

/sandbox

The panel has tabs for Mode (how sandboxed commands are approved), Overrides (whether a failed command may fall back to running unsandboxed) and Config (the settings in effect). On Linux or WSL2 it also tells you if a dependency is missing. You can instead set sandbox.enabled to true in a settings file such as ~/.claude/settings.json to turn it on for every project; see which settings file wins.

One thing to know: if the sandbox cannot start because a dependency is missing or the platform is not supported, Claude Code by default runs commands without sandboxing. Setting sandbox.failIfUnavailable to true makes it exit at startup instead.

What commands can reach by default

• Writes: the working directory, a per-user temp directory and any directories you added.
• Reads: most of the machine, including credential files such as ~/.ssh and ~/.aws/credentials. Reading is not restricted unless you restrict it.
• Network: no direct route out. Connections go through a proxy on your machine that checks each host against your allowed domains, which start empty. What happens to a host that is not on the list depends on your permission mode: in manual mode you get a prompt, in auto mode it is refused unless the command named the host and the classifier approved it.
• Environment variables: inherited from Claude Code, including any secrets in its environment.

Check that it works

Ask Claude to run these two commands. Typing them yourself at the ! prompt does not test the sandbox.

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

Inside the sandbox the first fails (Operation not permitted on macOS, Read-only file system on Linux and WSL2) and the second fails with Could not resolve host. If Claude asks to retry a failed command outside the sandbox, decline. If the touch succeeds, delete the file and check /sandbox.

Two modes

• Auto-allow: a command that runs inside the sandbox is approved without a prompt. Deny rules still apply, and ask rules such as Bash(git push *) still prompt. Note that this includes commands that change files inside the boundary, even in manual permission mode where the file-edit tools would ask.
• Regular permissions: every Bash command goes through the normal permission flow, even when sandboxed. More control, more prompts.

The sandbox's auto-allow mode is not the same thing as the permission mode called auto. Auto-allow approves a command because the sandbox contains it; auto mode uses a classifier to review actions. They work independently and can be combined. See permission modes.

The escape hatch

When a command fails inside the sandbox, Claude can ask to retry it outside. Who approves that depends on your permission mode, and an allow rule that matches the command also approves the retry without a prompt. If you do not want that route to exist, set "allowUnsandboxedCommands": false in the sandbox settings (the Overrides tab calls it strict sandbox mode). Commands that match excludedCommands also run outside the sandbox.

Widen or narrow it

Tools that must write outside the working directory need a specific path, rather than being excluded from the sandbox:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

To stop sandboxed commands reading your whole home directory while keeping the project readable, put this in the project's .claude/settings.json (there, . means the project root):

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Sandbox paths use ordinary conventions (~/.kube is under your home directory, /tmp/build is absolute), which differ from the path style in Read and Edit permission rules. Network access is widened with network.allowedDomains.

Its limits

The docs are direct about this: sandboxing reduces risk but is not a complete isolation boundary.

• The network proxy decides from the hostname and by default does not inspect encrypted traffic. Allowing a broad domain such as github.com can create a path for data to leave.
• Allowing a Unix socket such as Docker's can effectively hand over the host. Broad write access to directories on your PATH or to files like .bashrc can lead to code running outside the boundary.
• Effective sandboxing needs both file and network isolation. Check that a wide allowWrite, a broad domain or an excludedCommands entry does not undo a restriction on the other side.

The sandbox works alongside permission rules, not instead of them: rules decide which tools Claude may use and are checked before a tool runs, while the operating system enforces the sandbox on the running process. For anything security-related you want both. See best practices for how deny rules, hooks and the sandbox fit together, and debug your configuration if a setting seems ignored. The docs' troubleshooting section covers tools that need special handling, such as docker and git over SSH.

This follows Anthropic's sandboxing documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case (we could not test the sandbox on every platform). Settings and platform support change between versions, and where this page and the documentation disagree, the documentation wins. This page is general information, not a security audit of your setup.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.