lockstep
5 min readNaman Jain

Claude Code sandbox: what it isolates and how to set it up

What the Claude Code Bash sandbox restricts, what runs outside it, how to turn it on with /sandbox, auto-allow mode, and settings to protect credentials.

Permission prompts answer "should Claude run this command?" The sandbox answers a different question: "if it runs, what can it reach?" A test script that tries to read ~/.aws/credentials or call an unknown host is a different risk from one that stays inside the project, and the sandbox enforces that difference at the operating system level.

This guide covers what the Claude Code sandbox restricts, what it doesn't, and how to set it up, from Anthropic's sandboxing documentation, checked on 16 November 2026.

What the sandbox restricts

The sandbox wraps the shell commands Claude runs, including Bash, PowerShell, and Monitor commands and every process they start. Default limits:

AccessDefault
WritesThe working directory, a per-user temp directory, and directories you added. Protected paths stay write-denied
ReadsMost of the machine, including credential files such as ~/.ssh and ~/.aws/credentials
NetworkNo direct route out. A local proxy checks every host against your allowed domains, which start empty
Environment variablesInherited from Claude Code, including any secrets in it

Two defaults surprise people: reads are broad, and environment variables pass through. Both need explicit settings, covered below.

It runs on macOS, using the built-in Seatbelt framework, and on Linux and WSL2, using bubblewrap and socat. On native Windows, commands run unsandboxed; use WSL2. Claude Code builds it on the open-source @anthropic-ai/sandbox-runtime package.

What runs outside it

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

  • Built-in file and web tools. Read, Edit, Write, WebFetch, and WebSearch follow permission rules instead. A sandbox read rule doesn't stop the Read tool.
  • Other processes Claude Code starts: hooks, local MCP servers, the status line command, and similar helpers.
  • Commands you type yourself at the ! prompt, in most sessions.
  • Excluded commands listed in excludedCommands.
  • Unsandboxed retries Claude asks for, usually after a command fails in the sandbox.

To put everything behind one boundary, run Claude Code itself in a container, a virtual machine, or the sandbox runtime.

Turn it on

Run /sandbox in a session. The panel shows the settings and, on Linux, whether dependencies are missing. Or set it in settings:

{
  "sandbox": {
    "enabled": true
  }
}

Two sandbox modes

Both enforce the same file and network limits. They differ in prompting:

  • Auto-allow mode. A command that runs inside the sandbox is approved without a prompt. Deny rules, ask rules such as Bash(git push *), and critical-path rm commands still apply.
  • Regular permissions mode. Sandboxed commands still go through the normal permission flow.

Anthropic's permission modes guide pairs Manual mode with auto-allow as a way to iterate with fewer prompts and no classifier.

Settings worth adding

Let a tool write somewhere specific, rather than excluding it from the sandbox:

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

Block reads of your home directory except the project. Put this in the project's .claude/settings.json, where . means the project root:

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

When read rules overlap, the narrower path wins, and a deny inside a broader allow still holds, so a wide allow can't silently re-expose a secret.

Protect credentials with the credentials block, which denies files and unsets environment variables for sandboxed commands:

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

Filesystem lists merge across settings files rather than replacing each other. Sandbox paths use normal conventions, ~/ for home and absolute paths as written, which differs from Read and Edit permission rules.

For organizations

Managed settings can turn the sandbox on for everyone and stop developers from widening the policy. The documentation covers enforcement and locks under its organization section. For delivering managed settings, see Claude Code managed settings.

Common problems

The documentation's troubleshooting section lists frequent issues: commands failing with a host-not-allowed error (add the domain to allowed domains), jest hanging, Go-based CLIs failing TLS checks on macOS, browser-based auth flows failing, and docker commands failing inside the sandbox. Check that section before excluding a tool entirely.

What a sandbox can't judge

A sandbox stops a command from reaching the wrong files or hosts. It can't tell whether the code being written is the code the team agreed to. A perfectly sandboxed session can still ship a feature the product lead cut last week.

Where Lockstep fits

Lockstep covers that question. It captures decisions from PRDs, Slack, and pull requests, makes each binding when its owner approves it, and briefs Claude Code on the ones that apply at the start of each session. It runs alongside your sandbox and permission settings, not in place of them.

Session briefings work with Claude Code today. See how it works.

Sources checked 16 November 2026

For permission rules and modes, see Claude Code permissions. For unattended runs, see Claude Code best practices. For choosing a permission mode, see Claude Code plan mode vs auto mode vs accept edits. For security scanning and safe setup, see Claude Code security.

Frequently asked questions

What does the Claude Code sandbox do?
It puts an operating-system boundary around the shell commands Claude runs and the processes they start. By default, commands can write only to the working directory, a per-user temp directory, and directories you added, and they have no direct network route out; connections go through a proxy that checks each host against your allowed domains.
How do I turn on the Claude Code sandbox?
Run /sandbox in a session, or set sandbox.enabled to true in a settings file such as ~/.claude/settings.json. It is off by default. On Linux and WSL2 it needs bubblewrap and socat; on macOS it uses the built-in Seatbelt framework.
Does the Claude Code sandbox work on Windows?
Not natively. On native Windows, Claude Code runs commands unsandboxed. To use the sandbox on a Windows machine, run Claude Code inside a WSL2 distribution.
What does the sandbox not cover?
Claude's built-in file and web tools, such as Read, Edit, and WebFetch, which follow permission rules instead, plus hooks, local MCP servers, and the status line command. Commands you type at the ! prompt, excluded commands, and approved unsandboxed retries also run outside it.
Can the sandbox read my credentials?
By default, sandboxed commands can read most of the machine, including files like ~/.ssh and ~/.aws/credentials, and they inherit environment variables. Use the sandbox.credentials setting to deny those files and unset variables such as GITHUB_TOKEN for sandboxed commands.

Keep reading