Claude Code Sandbox: Limit Files and Network for Bash

The Claude Code sandbox is a boundary that the operating system enforces around the shell commands the agent runs. You choose which files those commands can reach and which network domains they can contact. Because the operating system applies the limits while a command runs, Claude Code can run sandboxed commands without asking you to approve each one. This guide shows how to turn it on, tune it and check what it does not cover.

It is a different tool from permission rules. Rules decide whether Claude may attempt a tool call; the sandbox decides what a running command can touch. If you have not set rules yet, read Claude Code Permissions: Allow, Deny Rules and Modes first, then come back.

What does the Claude Code sandbox restrict?

According to the Claude Code documentation, the limits apply to Bash, PowerShell and Monitor commands and to the processes they start. The defaults are:

Two details matter. First, reads are wide open by default, so a sandboxed command can read your SSH keys unless you deny that. Second, the environment is inherited, so a secret exported in your shell is visible to commands. Both can be changed with settings, shown below.

The sandbox runs on macOS, Linux and WSL2. On native Windows, Claude Code runs commands unsandboxed; to use the sandbox there, run Claude Code inside a WSL2 distribution. It is built on the open source @anthropic-ai/sandbox-runtime package. On macOS it uses the built-in Seatbelt framework; on Linux and WSL2 it relies on bubblewrap and socat.

How do I turn on the sandbox?

The sandbox is off by default. Start a session and run:

/sandbox

The panel has Mode, Overrides and Config tabs. Config shows the resolved settings. If the panel shows only a Dependencies tab, a required package is missing: install it, restart Claude Code and run /sandbox again.

Pick a mode on the Mode tab:

• Auto-allow: sandboxed commands run without a prompt. Some commands still go through the normal permission flow, including those that run outside the sandbox (see below).
• Regular permissions: the usual prompts stay even when commands are sandboxed.

To enable the sandbox across all your projects, set sandbox.enabled to true in ~/.claude/settings.json. To try it for one session without writing a file:

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

That command also closes the escape hatch described later, so a blocked command stays blocked.

One warning from the docs: by default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. To make it exit at startup instead, set sandbox.failIfUnavailable to true. Teams that treat the sandbox as a security gate should use it.

To check the sandbox is working, ask Claude to run touch ~/sandbox-probe. Inside the sandbox it should fail with Operation not permitted on macOS or Read-only file system on Linux and WSL2. Do not type the test yourself at the ! prompt, because that usually runs outside the sandbox.

How do I allow writes outside the project?

Tools such as kubectl, terraform or npm sometimes write outside the working directory. Grant the specific path rather than removing the tool from the sandbox:

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

These paths are enforced by the operating system, so child processes respect them too. There is also filesystem.denyWrite to block writes to specific paths.

How do I stop commands reading secrets?

Reads default to most of the machine. To block your home directory but keep the project readable, put this in the project's .claude/settings.json:

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

allowRead re-opens reading inside a region that denyRead blocks. The location matters: in project settings, . resolves to the project root, while the same lines in ~/.claude/settings.json resolve . to ~/.claude, so your project files would stay blocked.

The settings reference also lists a sandbox.credentials group that hides or masks credential files and environment variables inside the sandbox, and the docs name the CLAUDE_CODE_SUBPROCESS_ENV_SCRUB variable for environment secrets. Check the sandbox page for the exact options on your version.

How do I allow network hosts?

Allowed domains start empty. The first time a command needs a new domain, Claude Code prompts for approval. In auto mode, Claude instead names the hosts a command needs on the command itself so the classifier can review them with it. To pre-approve hosts, use network.allowedDomains:

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

network.deniedDomains blocks domains, even inside an allowed wildcard. If you want the opposite trade, filesystem.disabled turns off filesystem isolation while keeping network isolation. It is accepted only in user or managed settings, not in project files.

What happens when a tool does not work in the sandbox?

You have three choices, from safest to riskiest.

1. Widen the boundary a little. Add one directory with allowWrite or one host with allowedDomains. The command stays sandboxed.
2. Exclude the command. Commands matching excludedCommands run outside the sandbox:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker compose *"]
  }
}

Excluded commands still go through the regular permission flow, but they run unsandboxed. Keep patterns narrow: a pattern that covers a script in your working directory, or a tool that acts on a file there, can let Claude write that file and then run it outside the sandbox.

3. Let Claude retry unsandboxed. When a command fails in the sandbox, Claude can ask to run it again outside it, using the dangerouslyDisableSandbox parameter. How that request is approved depends on your permission mode, and a matching allow rule such as Bash(curl *) approves the retry as well. See the docs section on the unsandboxed retry for the per-mode behavior.

To remove the retry entirely, set allowUnsandboxedCommands to false; the Overrides tab presents this as strict sandbox mode. If you would rather be asked on every retry, add an ask rule for Bash(dangerouslyDisableSandbox:true).

Why does auto-allow still prompt sometimes?

Some sandboxed commands go through the normal permission flow anyway, typically because a prefix can change which program runs. An allow rule stops the recurring prompt, but it must match the whole command, including any variable assignment at the front. For example, a rule for npm test will not cover FOO=bar npm test; the rule needs to include the assignment. Remember that an allow rule also approves an unsandboxed retry of the same command.

What does the sandbox not cover?

The sandbox wraps shell commands only. These run outside it:

• Built-in file and web tools (Read, Edit, Write, WebFetch, WebSearch). A denyRead entry does not stop the Read tool, and allowedDomains does not limit WebFetch. Those follow permission rules.
• Command hooks, local MCP servers, plugin monitors, LSP servers, and helpers such as your status line command and apiKeyHelper. They run with your full access.
• Commands you type yourself at the ! shell-mode prompt, in most sessions.
• Excluded commands and unsandboxed retries, as described above.

So pair the sandbox with deny rules for the file tools, and treat hooks and MCP servers as trusted code. If you need one boundary around everything, the docs say to run the Claude Code process itself in a container, virtual machine or the sandbox runtime. For automation, see Claude Code Headless in CI for permission choices in non-interactive runs.

How do I enforce it for a team?

Use managed settings. The settings reference marks several keys as managed-only, including sandbox.network.allowManagedDomainsOnly, which locks the network allowlist to managed settings, and sandbox.filesystem.allowManagedReadPathsOnly, which stops developers re-opening read paths your organization blocked. Combine these with failIfUnavailable so a machine without the dependencies does not fall back to running unsandboxed.

A sensible starting setup

1. Run /sandbox and pick auto-allow.
2. Deny reads of ~/ and allow . in project settings.
3. Add only the write paths and domains your build actually needs.
4. Set allowUnsandboxedCommands to false for unattended runs.
5. Add deny rules for the file tools on secrets, since the sandbox will not.
6. Set failIfUnavailable to true where the sandbox is a requirement.

Conclusion

The sandbox turns "approve every command" into "approve the boundary once". It works best when you keep reads narrow, grant writes and hosts one at a time, and shut the unsandboxed retry for unattended work. It is not a full container: file tools, hooks and MCP servers sit outside it, so treat it as one layer next to permission rules. If you run several agents at once, as Atlas teams do, the same idea applies per session: each one needs its own boundary.