Permission rules decide whether Claude may attempt an action. The sandbox is an operating system boundary around the shell commands it runs, limiting which files and network hosts they can reach. Rules are about intent and approval. The sandbox enforces limits while a command runs. Use both.
What the sandbox restricts
Anthropic's sandboxing documentation describes two independent layers. Filesystem isolation controls which paths sandboxed commands can read and write. Network isolation sends connections through a proxy that checks each host against your allowed domains, which start empty.
It runs on macOS, Linux and WSL2. On native Windows, commands run unsandboxed, so use WSL2 if you need it. On macOS it uses the built-in Seatbelt framework. On Linux and WSL2 it relies on bubblewrap and socat.
What runs outside it
The page is explicit that the sandbox covers shell commands only. Claude's file tools, MCP servers and hooks run outside it. That is why file access needs permission rules, such as Read deny rules, and why MCP servers need their own review.
Two modes
In auto-allow mode, sandboxed commands run without prompting. In regular permissions mode, the normal prompts still appear even for sandboxed commands. In both, the same filesystem and network limits apply. The difference is only whether commands are auto-approved.
Failing closed
Two settings matter for teams:
- By default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. Setting
sandbox.failIfUnavailableto true makes it exit at startup instead. - Commands that fail under the sandbox can fall back to running unsandboxed unless you set
allowUnsandboxedCommandsto false. The docs also describeexcludedCommandsfor tools that cannot work inside the sandbox, which run with no filesystem limits and no network proxy.
Each escape hatch is a place where the boundary is weaker than it looks.
A caution on turning off layers
The documentation warns that with filesystem isolation off and commands auto-allowed, a command can write files that later commands run, such as shell startup files or executables on the path, and use them to widen its own access. Switch filesystem isolation off only for workloads you trust.
Why not one or the other
A rule such as a deny on curl matches the command text and does not match the same program called by path or inside sh -c. The sandbox network allowlist does not care how the call is spelled. In the other direction, the sandbox has no idea that a particular edit to a particular file is something you never want, while a deny rule can say so.
Quick check
Does the sandbox protect against a malicious MCP server?
No. The documentation says MCP servers run outside the sandbox. Review and restrict them separately.
What happens if the sandbox cannot start?
By default Claude Code runs commands unsandboxed. Set the fail-if-unavailable option to true to exit instead.
Sources
Last reviewed: 19 October 2026.
