What Is the Claude Code Sandbox? Filesystem & Network Isolation for Safe Automation (2026)

Use Claude Code long enough and you hit this dilemma. It asks "may I run this?" on every command, and your flow keeps stalling. But turning off all prompts with --dangerously-skip-permissions (bypass permissions) means a prompt injection or a slip of the hand could touch files all over your machine. Safety versus automation — long treated as a trade-off.

What breaks that binary is the sandbox. If you fence off "what can be touched" at the OS level up front, commands can run freely inside the fence without prompts, yet nothing can reach outside it. This article lays out, from a practitioner's angle, what the Claude Code sandbox isolates and how, how to start with /sandbox, how to configure it in settings.json, how it differs from permission modes, and the limits you must not over-trust.

1. Why you need a sandbox

Claude Code is an AI agent that actually does things — running tests, rewriting files. That is exactly why it stops to ask "may I run this?" before risky commands. For safety, that is correct. But when dozens of prompts land in a day, work fragments, and eventually you hit Enter without reading. That is "permission fatigue."

A tired developer reaches for --dangerously-skip-permissions (a.k.a. YOLO mode), which turns off all prompts. It is comfortable, and — as the name says — dangerous. Three threats bare their teeth at once.

The sandbox's idea is simple: stop asking "what should I confirm?" every time, and fence "how far can this reach?" up front. The fence is enforced not by Claude's own judgment but by the OS (the kernel), so even if it is hijacked, and even if an allowed command does more than its name suggests, nothing escapes the boundary. That is why commands inside the fence are safe to run without prompts — the binary of fatigue-versus-full-bypass disappears. In its official engineering post, "Making Claude Code more secure and autonomous with sandboxing," Anthropic reports that in internal use it safely reduced permission prompts by 84% (published October 2025).

2. What the sandbox is — two isolations

The Claude Code sandbox draws two boundaries around Bash commands (and every child process they spawn). The two must work as a set — either one alone leaves a gap (see §7).

The crux is that it does not rely on Claude behaving well. The boundary is enforced by the OS's own security machinery — macOS uses the built-in Seatbelt, Linux/WSL2 uses bubblewrap. So the same boundary extends to scripts a command invokes and to grandchild processes. Think of it not as a polite request to the model, like AI guardrails, but as a physical wall that holds mechanically.

3. Getting started — /sandbox and supported OSes

The sandbox is built into Claude Code. No extra account or tool is required. In a session, run:

/sandbox

A panel opens with three tabs. Mode (how sandboxed commands are approved — next section), Overrides (whether a command that fails under the sandbox may fall back to running unsandboxed), and Config (view the resolved settings). On Linux/WSL2, if a required package is missing, a Dependencies tab appears instead and tells you what to install.

Prerequisites per OS

On Linux/WSL2, install bubblewrap (the unprivileged sandboxing tool that enforces filesystem isolation) and socat (the relay that routes traffic to the proxy).

# Ubuntu / Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

One handy thing to enable is the seccomp filter (which adds Unix-domain-socket blocking). It is optional; install it with npm install -g @anthropic-ai/sandbox-runtime. The /sandbox Dependencies tab shows the status of ripgrep, bubblewrap, socat, and the seccomp filter. After installing packages, restart Claude Code and reopen /sandbox (the check runs at startup).

4. The two modes (auto-allow / regular)

The Mode tab chooses how commands inside the sandbox are approved.

In both modes the filesystem and network boundaries are identical; the only difference is "auto-allow versus prompt." Note that even in auto-allow mode these safety valves stay live:

• Explicit deny rules always take precedence
• rm / rmdir targeting /, your home directory, or other critical system paths still prompt
• Content-scoped ask rules like Bash(git push *) still force a prompt, even inside the sandbox

5. Configuring it in settings.json

Choices in the /sandbox panel are written to the project's .claude/settings.local.json (not committed to git). To keep it always on across all projects, put sandbox.enabled: true in your user settings at ~/.claude/settings.json. It lives in the same settings.json family as permission rules (allow/ask/deny).

Add write targets, deny reads

By default you can write only to the working directory and the temp folder. If kubectl or terraform needs to write elsewhere, add paths with allowWrite. Conversely, you can block reads of sensitive folders.

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

The example above denies reads of the whole home directory while still allowing the current project (. resolves to the project root when the config lives in project settings). Paths are enforced at the OS level, so they apply equally to child processes like npm and terraform.

Protect credentials

An important pitfall: the default for reads is "broadly allowed," so ~/.aws/credentials and ~/.ssh/ are readable as-is. The dedicated sandbox.credentials setting (a relatively recent feature) declares files to deny reading and environment variables to unset.

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" }
      ]
    }
  }
}

Allow destinations

The network starts with zero destinations. A new domain prompts the first time it is reached (in recent versions at the time of writing, approving once means no re-prompt for the rest of the session). Pre-register hosts you do not want to be asked about in allowedDomains. With org-distributed managed settings, you can also block anything outside the allowlist automatically instead of prompting.

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

6. Relationship to permission modes and rules

They are easy to conflate, but Claude Code's safety machinery has three layers with distinct jobs. The sandbox is one of them — it does not replace the other two; it complements them.

The decisive difference is "when and by whom" each takes effect. Permission rules and modes are decided before execution, by Claude Code, from the command string. The sandbox binds the process during execution, by the OS — so whatever the model chose, and even if an allowed command does more than its name implies, the boundary does not budge.

That is also the decisive gap from --dangerously-skip-permissions (bypass). Bypass only removes prompts; the environment stays wide open. The sandbox's auto-allow, by contrast, can skip prompts because the OS wall is there. The old iron rule — if you use bypass mode, only ever inside an isolated container or VM — is something the sandbox lets you shift to the safe side even on your everyday machine.

7. Limits and caveats — do not over-trust it

The sandbox is powerful, but it is not complete isolation. Before leaning on it as a hard security boundary, know the limits the docs spell out.

One more thing to internalize: the scope is Bash only — built-in Read/Edit/Write, MCP servers, and hooks are separate. To isolate the entire process, including Skills and MCP, wrap the Claude Code process itself with the official open-source @anthropic-ai/sandbox-runtime (published on GitHub and npm, a research preview released in October 2025). Its practical role is not a "wall" against a determined attacker, but a "safety harness" that cuts accidents and runaways by orders of magnitude.

8. When to reach for dev containers or VMs

The sandbox is not Claude Code's only isolation option. Convenience and strength of isolation trade off, so choose by purpose.

The rule of thumb: keep the built-in sandbox always on to cut daily prompts, and only step up to sandbox-runtime, containers, or VMs when you run unattended or handle untrusted dependencies. For work that reaches production — like letting AI operate the cloud — pairing least-privilege credentials with a stronger isolation tier buys peace of mind.

Summary

The sandbox breaks the very premise that safety and automation must trade off. Just open /sandbox once — that alone changes how you hold Claude Code's reins. For the exact, current configuration reference, treat the official sandbox settings documentation as your primary source.

FAQ