How to Use Claude Code Sandbox | Safe Automated Execution with /sandbox

What Is the Claude Code Sandbox — The Boundaries /sandbox Enforces

The sandbox is a feature that enforces at the OS level which files and network domains the Bash commands Claude Code executes — and their child processes — are allowed to touch. Instead of approving each command individually, you define the boundaries in advance, allowing long tasks like builds and tests to run without interruption.

The key point is that enforcement relies on the OS security infrastructure, not on trust or instruction text. Even if an approved command attempts to do more than its name implies, the boundary applies to the running process itself and does not depend on what the model chose. The primary source for the specification is the Claude Code official documentation "Configure the sandboxed Bash tool".

How to Enable the Sandbox (the /sandbox Command)

Run the following command in a session to open the sandbox panel.

1. Run /sandbox in a Claude Code session.
2. In the Mode tab, choose your approval method (auto-allow for automatic approval, or regular permissions to keep the traditional prompts).
3. In the Overrides tab, decide whether commands that fail under the sandbox should fall back to running without sandboxing (allowUnsandboxedCommands).
4. In the Config tab, review the resolved sandbox configuration.
5. Have Claude run commands like builds or tests, and confirm that a prompt appears on the first access to a new domain.

Selecting a Mode in the panel writes to .claude/settings.local.json (excluded from git) in the project root. If you want to use the sandbox across all projects, set sandbox.enabled to true in your user settings at ~/.claude/settings.json. If only the Dependencies tab appears when you open /sandbox, that is a sign that required packages are missing.

Setup Differences Between macOS and Linux/WSL2

The OS-level enforcement implementation differs by environment.

• macOS: No additional installation required. Uses the built-in Seatbelt framework.
• Linux / WSL2: Requires bubblewrap for isolation and socat to relay communications to the proxy.

On Ubuntu/Debian, run sudo apt-get install bubblewrap socat; on Fedora, run sudo dnf install bubblewrap socat. After installation, restart Claude Code and check the Dependencies tab in /sandbox to verify the presence of ripgrep, bubblewrap, socat, and seccomp filters. If the seccomp filter responsible for blocking Unix domain sockets is missing, you can add it with npm install -g @anthropic-ai/sandbox-runtime.

Note that native Windows is not supported — on Windows, use Claude Code running inside WSL2. WSL1 does not work because it lacks the kernel features that bubblewrap requires. Also, on Ubuntu 24.04 and later, AppArmor's default policy may block bubblewrap from creating user namespaces; in that case, add an AppArmor profile for bwrap.

How Filesystem Isolation Works and the allowWrite Setting

The default behavior is as follows:

• Writes: Only the working directory (and its subdirectories) and the session temp ($TMPDIR) are writable. Paths like ~/.bashrc and /bin/ are protected and cannot be modified without explicit permission.
• Reads: In principle, the entire computer is readable except for a few denied directories. Note that by default, ~/.aws/credentials and ~/.ssh/ are also readable.

If tools like kubectl, terraform, or npm need to write outside the working directory, use sandbox.filesystem.allowWrite to permit those paths.

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

To protect credentials, use denyRead to block access, then use allowRead to re-permit only the necessary locations. The example below blocks read access to the entire home directory while allowing reads only within the project root (when placed in the project's .claude/settings.json, . resolves to the project root).

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

Because these rules are enforced at the OS level, they apply not just to Claude's file tools but to every CLI spawned as a child process.

How Network Isolation Works and the allowedDomains Setting

Network control is handled by a proxy server running outside the sandbox.

• No pre-approved domains: By default, no domains are allowed, and a prompt appears the first time a new domain is accessed. Add frequently used domains to allowedDomains for pre-approval.
• Organization lockdown: Setting allowManagedDomainsOnly in managed settings causes non-approved domains to be automatically blocked without a prompt, with only the managed allowedDomains taking effect.
• Coverage: Restrictions apply to all scripts, programs, and child processes spawned by a command.

An important limitation: the built-in proxy filters only by the requested hostname and does not terminate or inspect TLS. This means that allowing a broad domain like github.com can potentially create a data exfiltration path via domain fronting. For stricter control, set up a custom proxy that terminates and inspects TLS using network.httpProxyPort and inject its CA certificate into the sandbox. See Security limitations in the official sandboxing documentation for details.

Differences from Permission Rules and Permission Modes

The sandbox operates on a separate layer from the permission system.

• Permission rules: Evaluate which tools may be used, before execution. They apply to all tools — Bash, Read, Edit, WebFetch, MCP, and so on.
• Sandbox: Enforces at the OS level on the running process what files and network resources the Bash command and its child processes can touch.

Furthermore, /sandbox is not a permission mode. A permission mode decides "whether to execute a tool call or prompt for confirmation beforehand," while the sandbox restricts "what an executed command can touch." The sandbox's auto-allow means "Bash is automatically approved because the sandbox containment is in place" — it is independent of auto mode, in which the classifier reviews actions, and the two can be used together. Even in auto-allow mode, rm targeting / or home, content-scoped ask rules such as Bash(git push *), and explicit deny rules continue to trigger prompts or rejections.

Enforcing the Sandbox Across an Organization (Managed Settings)

To make the sandbox mandatory for all developers, distribute the sandbox key via an MDM-managed file or Claude.ai's server-managed settings.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable: Instead of warning and continuing without a sandbox when it cannot start (e.g., due to missing bubblewrap), this stops Claude Code from launching at all.
• allowUnsandboxedCommands: false: Disables the dangerouslyDisableSandbox loophole that would otherwise allow failed commands to be retried outside the sandbox.

Additionally, it is recommended to add ~/.aws and ~/.ssh to denyRead to block their default readability, and to keep excludedCommands narrow. To restrict readable paths to only those defined in managed settings, set allowManagedReadPathsOnly to true. Boolean keys give priority to managed values, but array keys are merged across all scopes, so be careful about excludedCommands growing too large.

What the Sandbox Protects Against — and Its Limitations

The sandbox reduces risk but is not a complete isolation boundary. Keep these design-level limitations in mind.

• TLS not inspected: As noted above, broad domain allowances can become exfiltration paths.
• Privilege escalation via Unix sockets: Allowing /var/run/docker.sock effectively grants access to the host.
• Write privilege escalation: Allowing writes to executables on $PATH or to .bashrc can lead to code execution in other contexts.
• Settings file protection: The sandbox automatically denies writes to settings.json across all scopes to prevent its own policy from being overwritten.
• Scope: The sandbox constrains child processes of Bash. Read/Edit/Write are managed separately by the permission system, and computer use runs on the actual desktop. To exclude credentials from child processes, use CLAUDE_CODE_SUBPROCESS_ENV_SCRUB.

The official documentation explicitly states that "both filesystem and network isolation are required for the sandbox to be effective." Loosening either one opens up avenues for exfiltrating SSH keys or hijacking network access.

When to Use Docker or Dev Containers Instead

/sandbox is a lightweight, in-process boundary well suited for reducing command approvals during local development. When stronger isolation is needed, Docker, dev containers, or VMs are the alternatives. The Docker official documentation on Claude Code integration shows how to run Claude Code inside a container. The same OS primitives that Claude Code uses internally are also available as a standalone package, @anthropic-ai/sandbox-runtime, which wraps an entire process.

Note that attempting to use --dangerously-skip-permissions as root inside a container will be rejected on Linux/macOS. For autonomous execution inside a container, use a dev container configuration that runs as a non-root user. The official "Sandbox environments" documentation provides detailed comparisons of multiple isolation approaches — choose based on your threat model.

Common Issues and How to Fix Them

• host-not-allowed error: The CLI simply cannot reach a specific host. Approve it at the prompt and it will work inside the sandbox going forward.
• jest hangs: watchman is incompatible with the sandbox. Use jest --no-watchman.
• gh, gcloud, or terraform fail TLS verification on macOS: These can fail under Seatbelt, so add them to excludedCommands to run them outside the sandbox.
• docker command fails: Docker is incompatible with the sandbox — add docker * to excludedCommands.
• bubblewrap fails to start inside a container: Unprivileged containers cannot mount /proc fresh, so enable enableWeakerNestedSandbox: true to let the outer container handle isolation (note that this weakens security).

Detailed troubleshooting is covered in the Troubleshooting section of the official sandboxing documentation. The sandbox is a practical middle ground — enforcing OS-level boundaries while reducing permission prompts. A safe way to start is with three steps: try /sandbox in auto-allow mode, block credential access with denyRead, and add only the domains you need to allowedDomains.