Sandboxing and OS-Level Isolation

Permissions tell Claude Code what it's allowed to do. Sandboxing tells the operating system what it can physically do. The gap between those two is where security incidents happen.

Permissions vs. Sandboxing

Permissions are a sign on a door that says "Employees Only." It works because Claude Code respects the sign. But what if a prompt injection tricks it into ignoring the sign? A sign doesn't physically stop anyone from walking through.

Sandboxing is the deadbolt. Enforced at the OS level. Even if Claude Code tried to write to ~/.bashrc or phone home to some random server, the kernel blocks it. No amount of clever prompting gets past a kernel-level restriction.

Permissions are layer one (which tools Claude Code can use). Sandboxing is layer two (OS-level enforcement for Bash commands). You want both.

How Filesystem Isolation Works

With sandboxing enabled, Claude Code can only write to your current working directory and its subdirectories. Period. It can read files from most of your computer (some sensitive directories are blocked), but write access is locked to your project.

Create files in your project? Yes. Edit source code? Yes. Touch /usr/bin/? No. Edit ~/.bashrc? No. Drop files into your Downloads folder? No.

On macOS, this is enforced through Seatbelt (Apple's built-in sandbox framework). On Linux and WSL2, bubblewrap. Actually, wait: WSL1 doesn't support sandboxing at all. If you're still on WSL1, this is a good reason to upgrade.

If you need Claude Code to write to additional directories, configure them explicitly:

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

Path prefixes matter. // means absolute path. ~/ means relative to home directory. Plain / means relative to wherever the settings file lives.

How Network Isolation Works

Filesystem restrictions alone aren't enough. If Claude Code can reach the internet freely, a malicious dependency or an injected prompt could exfiltrate your source code to an attacker-controlled server. Or download and run something nasty.

Network isolation handles this. A proxy server runs outside the sandbox, and all traffic from inside must go through it. Only approved domains get through. New domain? Claude Code prompts you.

And this applies to everything running inside the sandbox, not just Claude Code's direct requests. If it runs a bash script, and that script spawns a subprocess, and that subprocess tries to phone home, still blocked. No sneaking around it.

Enabling and Configuring the Sandbox

Enable sandboxing with /sandbox inside Claude Code. Linux and WSL2 users need bubblewrap first:

apt-get install bubblewrap socat

Two modes once it's enabled.

Auto-allow mode is where it gets interesting. Bash commands inside the sandbox execute without asking your approval. The sandbox already restricts what they can do, so clicking "approve" on every ls or grep is pointless. Commands that can't be sandboxed fall back to normal permission flow.

Regular permissions mode keeps the standard approval prompts even for sandboxed commands. You get OS-level protection either way, but auto-allow mode is where the productivity gains actually show up.

The whole point of sandboxing is solving approval fatigue. If you're clicking "approve" fifty times an hour, you stop reading what you're approving. Sandboxing lets you safely cut the prompts without cutting actual security.

Test Your Sandbox Boundaries

Verify it works. Enable sandbox mode, then ask Claude Code to write outside your project:

echo "test" > /tmp/sandbox-test.txt

If /tmp isn't in your allowWrite list, this fails. The sandbox blocks it. You can retry with dangerouslyDisableSandbox if you genuinely need it, which routes through the normal permission flow instead.

Try curling an unapproved domain too. The network proxy should prompt before allowing it.

Want to lock things down even further? Disable the escape hatch entirely:

{
  "sandbox": {
    "allowUnsandboxedCommands": false
  }
}

No fallback. Blocked is blocked.

What This Actually Protects Against

A sandboxed session can't modify system files like /bin/ or ~/.bashrc. Can't send your code to an attacker-controlled server. Can't download and run malicious scripts. If a compromised npm package tries something during install, the sandbox catches it.

The scenario worth worrying about is prompt injection. You ask Claude Code to read a file from the web, and that file contains hidden instructions to exfiltrate your SSH keys. Without sandboxing, permissions might catch it, might not, especially if you've gotten sloppy with auto-approvals. With sandboxing, the OS blocks it regardless. "Probably fine" vs. "actually safe" is a meaningful gap.

The sandbox runtime is open source (@anthropic-ai/sandbox-runtime on npm). You can inspect exactly how it works, which is more than most security tools offer.