What Claude Code's Sandbox Actually Does
The Bash sandbox lets Claude run most shell commands without stopping to ask your permission for each one, by containing what those commands can touch instead. You define which files and network domains are reachable, and your operating system enforces that boundary for every Bash command and its child processes. This is real OS-level enforcement, not a prompt-level filter Claude could reason its way around.
It ships built into Claude Code and runs on macOS, Linux, and WSL2. On macOS there's nothing to install, since it uses the built-in Seatbelt framework. On Linux and WSL2 it relies on two packages: bubblewrap for filesystem isolation and socat to relay network traffic through the sandbox proxy. Native Windows isn't supported - run Claude Code inside WSL2 there instead.
What It Restricts by Default
The sandbox has two independent layers, filesystem and network, and the defaults are asymmetric in a way that trips people up.
Sandbox defaults, out of the box
| Layer | Default behavior |
|---|---|
| Filesystem write | Only the current working directory and its subdirectories, plus the session temp directory |
| Filesystem read | The entire computer, except a small set of denied directories - this still includes credential files by default |
| Network | No domains pre-allowed. The first time a command needs a new domain, Claude Code prompts, and as of v2.1.191 that approval lasts for the rest of the session |
That middle row is the one worth reading twice. The default read policy still allows sandboxed commands to read files like ~/.aws/credentials and ~/.ssh unless you explicitly restrict them with sandbox settings. Turning on the sandbox does not, by itself, protect your credentials. That's a separate step.
The Gap Most Builders Miss: Credentials
Claude Code's sandbox settings give you a dedicated credentials block for exactly this gap. You list specific file paths and environment variables, and choose how they're protected: deny blocks them outright, mask lets a tool still authenticate without ever exposing the real secret to the command or its logs.
- deny: the file becomes unreadable inside the sandbox, and listed environment variables get unset before the command runs. Simple, but it also breaks any tool that legitimately needs that credential, like gh or npm.
- mask: the sandboxed command sees a placeholder value instead of the real one. When a request actually needs to reach an approved host, the sandbox proxy swaps the real credential back in on the way out. The command itself, and anything it logs, never holds the real value.
- There is no built-in credential deny list. Only the files and variables you explicitly name are protected - everything else stays readable at the sandbox's default, permissive read policy.
The Three-Gate Autonomy Check
I run this quick check before I let a Claude Code session go unattended for real, on top of the scoping I already do with the Leash Loop. The Leash Loop controls what Claude tries to do. The sandbox controls what it can actually reach if something goes sideways anyway. They're not the same layer, and you want both.
- Gate 1 - Sandbox is on. Run /sandbox and confirm it's active, not just installed. On Linux or WSL2, check the Dependencies tab isn't blocking it for a missing package.
- Gate 2 - Credentials are named, not assumed. List your actual credential files (SSH keys, cloud config, API tokens in env vars) under sandbox.credentials, with deny for anything you don't need Claude touching this session, and mask for anything a tool genuinely needs to authenticate with.
- Gate 3 - Network domains are scoped, not wide open. Pre-allow the specific domains the task needs rather than approving broad ones on the fly. A wildcard like an entire code-hosting domain is more permission than most tasks actually require.
None of this replaces reviewing the diff afterward. It's the layer that limits the damage in the window before you get back to your desk.
What the Sandbox Does Not Protect
Scope matters here and it's easy to overestimate. The sandbox isolates Bash subprocesses specifically. Several other things people assume are covered aren't.
- Claude's built-in Read, Edit, and Write tools don't go through the sandbox at all. They're governed by the separate permission system (allow/deny/ask rules), not by sandbox filesystem settings.
- --dangerously-skip-permissions bypasses this entirely. It skips protected-path checks too. The flag is blocked when running as root or via sudo on Linux and macOS, specifically because that combination removes too many safety nets at once.
- Docker is incompatible with the sandbox outright. If your workflow runs docker commands, they need to be listed in excludedCommands to run unsandboxed, which means they run with none of the above protection.
- Computer use - when Claude controls your actual screen and opens apps - runs on your real desktop, not in an isolated environment. It's gated by per-app permission prompts instead.
Inside Claude Code Club
Most builders find out the sandbox has gaps the hard way, mid-build, instead of reading the settings reference first. Inside Claude Code Club we share real sandbox and permissions configs from actual client builds, not just the default setup. Start with the [curriculum](/curriculum) or join us at https://www.skool.com/claudecodeclub/about for $9/month and bring the unattended run you're not fully comfortable with yet.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
Does Claude Code's sandbox protect my SSH keys and credentials automatically?
No, not by default. The sandbox's default read policy still allows sandboxed Bash commands to read your entire disk, including files like ~/.aws/credentials and ~/.ssh, unless you explicitly add them to sandbox.credentials with a deny or mask rule. Turning the sandbox on restricts writes and unapproved network access first - protecting credentials is a separate step you have to take yourself.
What's the difference between the sandbox and Claude Code's permission rules?
Permission rules decide whether a tool call runs at all, and apply to every tool - Bash, Read, Edit, WebFetch, MCP servers. The sandbox is narrower: it's OS-level enforcement that restricts what a Bash command can access at the filesystem and network level once it's already been allowed to run. They're complementary layers, not substitutes for each other.
Does the sandbox work on Windows?
Not on native Windows. The sandbox runs on macOS (using the built-in Seatbelt framework), Linux, and WSL2 (both using bubblewrap). If you're on Windows, run Claude Code inside a WSL2 distribution to get sandboxing.
Is running with --dangerously-skip-permissions safe if the sandbox is on?
The sandbox and permission modes are separate layers. --dangerously-skip-permissions removes the tool-call approval step and protected-path checks, and it's blocked outright when running as root or via sudo on Linux and macOS for that reason. Having the sandbox enabled does not make that flag safe to use casually on real work.
Where can I see real sandbox configs from actual client projects?
The Claude Code Club shares the sandbox and permission setups builders actually run on client work, not just the documented defaults. Join for $9/month at claudecodeclub.ai.
Last reviewed by David Iya on August 5, 2026
