12.9 Sandbox Design

The sandbox is the most "physical" layer in defense in depth—it restricts the execution environment of commands through OS-level mechanisms, so that even if the code itself is malicious, it cannot exceed the sandbox's boundaries.

Architecture

Claude Code uses the @anthropic-ai/sandbox-runtime package, integrated into the CLI through the SandboxManager adapter. The adapter is responsible for converting Claude Code's settings (permission rules, working directory, MCP configuration, etc.) into the sandbox runtime's configuration format.

Three-Dimensional Restrictions

The sandbox restricts command capabilities across three dimensions:

Filesystem restrictions:

• Writable scope: Project directory + temporary directory (/tmp/claude-\{uid\}/). Even if a command tries to write to ~/.bashrc or /etc/passwd, the filesystem sandbox will block it
• Always non-writable: Claude Code's own settings files (settings.json, settings.local.json)—preventing commands within the sandbox from achieving "sandbox escape" by modifying permission rules
• Readable scope: Project directory + system necessary paths (/usr/, /lib/, etc.). Can be extended through configuration

Network restrictions:

• Default policy depends on configuration. The system extracts the list of allowed domains from the WebFetch tool's allow permission rules
• allowManagedDomainsOnly option: Enterprises can lock it down to only allow domains specified in managed policies, blocking all other network access
• Domains in deny rules are added to the network blocklist

Process restrictions:

• macOS: Uses Apple's Seatbelt (sandbox-exec) framework, defining allowed system calls and resource access through declarative policy files
• Linux: Uses process namespaces for isolation, including mount namespace (filesystem view isolation) and network namespace (network isolation)

Path Pattern Conventions

Path patterns in sandbox configuration have special syntax:

Pattern	Meaning	Example
//path	Filesystem absolute path	//var/log -> /var/log
/path	Relative to settings file directory	/src -> \{settings-dir\}/src
~/path	User home directory	~/Downloads
./path or path	Relative path	Handled by sandbox runtime

autoAllowBashIfSandboxed

When both the sandbox and autoAllowBashIfSandboxed are enabled, sandboxed commands can skip permission confirmation and execute automatically. The logic is simple: if a command is already restricted by the sandbox to within the project directory, cannot access the network, and cannot modify system files, then its damage scope is effectively controlled, and there is no need for users to confirm each one individually.

However, there are several key exceptions:

• Commands with dangerouslyDisableSandbox set do not get auto-allowed
• Explicit deny rules still take effect
• Explicit ask rules still take effect

dangerouslyDisableSandbox

The naming of the dangerouslyDisableSandbox parameter is intentionally designed—the name itself serves as a security reminder.

• Necessary use cases: Some commands genuinely require system-level access, such as Docker operations (requiring /var/run/docker.sock), system package managers (apt/brew)
• Model must explicitly request it: The model needs to explicitly set this parameter in the tool call, and the user must also approve it in the dialog
• Other security layers remain in effect: Even with the sandbox disabled, Bash multi-layer security checks, permission rule matching, path constraints, and other defense layers remain active—this is the value of defense in depth

Source: src/utils/sandbox/sandbox-adapter.ts