What Claude Code's built-in sandbox covers, and what it doesn't

01What is the Claude Code sandbox?

Anthropic's documentation calls it the sandboxed Bash tool: a boundary the operating system enforces around the shell commands Claude runs on your machine. The limits apply to Bash, PowerShell and Monitor commands and to every process they start. It is off by default; you turn it on by running the /sandbox command in a session or by setting sandbox.enabled to true in a settings file. It is built on Anthropic's @anthropic-ai/sandbox-runtime package, which is Apache-2.0 licensed.

The purpose is fewer prompts without less safety. When Anthropic introduced it in October 2025, it reported that in internal use sandboxing reduced permission prompts by 84 percent. Because the OS enforces the limits while a command runs, Claude Code can run sandboxed commands without asking you about each one.

There are two modes. In auto-allow mode, a sandboxed command is approved automatically, though deny rules, content-scoped ask rules such as Bash(git push *) and rm on critical paths still apply. In regular permissions mode, every Bash command goes through the normal permission flow even when it runs sandboxed.

02Seatbelt vs bubblewrap: how it works on each platform

On macOS the sandbox uses Apple's built-in Seatbelt framework, so there is nothing to install. On Linux and WSL2 it uses bubblewrap for filesystem isolation and socat as the network relay, both installed from your package manager; an optional seccomp filter adds Unix domain socket blocking. WSL1 is not supported, and on native Windows Claude Code runs commands unsandboxed, so the docs recommend running it inside a WSL2 distribution.

The defaults are worth reading closely. Writes are allowed in the working directory, a per-user temp directory and directories you added, while protected paths such as .claude settings, .mcp.json, .bashrc, .gitconfig and Git hooks stay write-denied. Reads are allowed across most of the machine, including credential files such as ~/.ssh and ~/.aws/credentials, unless you add filesystem.denyRead entries or credentials rules. Environment variables are inherited from Claude Code, including any secrets in it.

• Writes: working directory, temp, added directories; protected paths denied.
• Reads: most of the machine by default; narrow with filesystem.denyRead and credentials.
• Network: no direct route; a local proxy checks hosts against network.allowedDomains, which starts empty.
• Environment: inherited, so scrub secrets with credentials or CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

03How the Claude Code sandbox network filter works

Sandboxed commands have no direct route out. On Linux and WSL2 they run in their own network namespace; on macOS, Seatbelt blocks every connection except the one to the sandbox proxy. Tools that honour proxy variables, such as curl, npm and git over HTTPS, connect once their host is allowed. Tools that ignore them, such as plain ssh and most database drivers, cannot connect even to allowed hosts, and UDP, HTTP/3 over QUIC and ping cannot leave at all. Hostnames that resolve only to local addresses, including the cloud metadata address, are refused, apart from localhost.

What happens to a host that is not on the list depends on your permission mode. You get a prompt in manual and acceptEdits mode; the connection is refused in dontAsk mode; and in bypassPermissions mode it is allowed without a prompt unless strictAllowlist or allowManagedDomainsOnly is on.

The filtering is domain-level. The docs say the built-in proxy decides from the client-supplied hostname and by default does not terminate or inspect TLS. They warn that allowing broad domains such as github.com can create paths for data exfiltration, and that code in the sandbox could potentially use domain fronting to reach hosts outside the allow-list. For stronger control they point to a custom proxy that terminates and inspects TLS.

04What runs outside the sandbox

The sandbox covers shell commands, not the whole agent. Claude's built-in file and web tools, 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. Command hooks, local MCP servers, plugin monitors, LSP servers and helper commands such as the status line and apiKeyHelper run with your full access.

Some shell commands also run outside it. A command you type at the ! prompt runs unsandboxed in most sessions. Commands matching excludedCommands run with no filesystem restrictions and no network proxy, so a wide pattern such as docker * gives broad access. And Claude can ask to retry a failed command unsandboxed, covered next. Anthropic's sandbox-environments page sums it up: the sandboxed Bash tool restricts Bash commands, while built-in file tools, MCP servers and hooks still run directly on your host.

05When commands fall back to running unsandboxed

There are two fallbacks. The first is the unsandboxed retry: when a command fails inside the sandbox, Claude may retry it with the dangerouslyDisableSandbox parameter. Who approves depends on the mode: you get a prompt in manual and acceptEdits mode, a classifier decides in auto mode, it is denied in dontAsk mode, and it runs without a prompt in bypassPermissions mode. An allow rule that matches the command also approves its unsandboxed retry.

The second is quieter. By default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. On a Linux machine without bubblewrap, or on native Windows, that means the boundary you configured is not there. Both fallbacks can be turned off, and administrators can lock the settings through managed settings.

• allowUnsandboxedCommands: false ignores dangerouslyDisableSandbox; /sandbox shows it as Strict sandbox mode.
• failIfUnavailable: true makes Claude Code exit at startup if the sandbox cannot run.
• Keep excludedCommands narrow and avoid broad allowedDomains entries.
• Leave allowUnixSockets and enableWeakerNestedSandbox off unless another boundary is in place.

06Where a VM layer fits on top

The docs are direct about scope: sandboxing reduces risk but is not a complete isolation boundary, and to put file tools, MCP servers, hooks and typed commands behind one boundary you run the Claude Code process itself in the sandbox runtime, a container or a virtual machine. They add that effective sandboxing needs both filesystem and network isolation, and that any approach allowing egress can still leak data the agent can read.

The layers are complementary. The built-in sandbox gives per-command limits and fewer prompts; whether it runs inside a given container or VM depends on that environment, and the docs warn that its enableWeakerNestedSandbox mode for Docker considerably weakens it. An outer VM adds what the built-in sandbox does not cover: MCP servers and hooks run inside it, the host's ~/.ssh and cloud credentials are simply absent, and the network rule is enforced outside the guest kernel.