Isolation guide

Configure the Claude Code Sandbox

Choose an isolation boundary, understand what it excludes, and verify the controls before running an agent.

Threat DB v2.29.0Updated September 12, 2026

What the sandbox protects

The operating system enforces filesystem and network boundaries after a command starts, including child processes and package lifecycle scripts.

Strong boundary

A permitted command cannot silently expand beyond the sandbox’s writable paths and network policy.

Separate from permissions

A permission rule matches command text. It cannot predict everything a package installer, shell script, or child process will do.

What it does not protect

Default readable paths, inherited environment variables, approved exclusions, compromised dependencies, and commands launched outside the sandbox remain separate risks.

Credential warning: file restrictions alone do not remove tokens inherited through environment variables. Configure both credential files and environment variable names.

Three silent failure modes

These traps usually surface as an operation error or timeout, not as a message explaining which exclusion failed.

Trap 1

The bare command never fires

"docker" matches the zero-argument command, not docker ps. Use a deliberately scoped pattern such as "docker *".

Trap 2

A match can unsandbox a compound call

A broad exclusion may remove the boundary for the entire compound shell call. Prefer subcommands such as "git push *".

Trap 3

A wrapper breaks the match

gh api and rtk gh api are different command strings. Account for wrappers introduced by hooks and tooling.

Start from an explicit configuration

Keep exclusions narrow, block sensitive files, name credential environment variables, and leave automatic Bash approval disabled until verified.

.claude/settings.json

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "excludedCommands": ["git push *", "git fetch *"],
    "credentials": {
      "files": ["~/.ssh", "~/.aws/credentials", "~/.config/gcloud"],
      "envVars": ["AWS_ACCESS_KEY_ID", "GITHUB_TOKEN"]
    }
  }
}

Treat this as a reviewable starting point. Paths and commands must match your operating system, repository, and actual toolchain.

Verify the boundary

Test the control itself. A valid JSON file only proves structure, not runtime isolation.

Confirm a permitted write succeeds inside the repository.
Confirm a write outside allowed paths fails.
Confirm denied credential files and environment variables are unavailable.
Test every excluded command with its real wrapper and arguments.
Verify denied network destinations fail within a bounded timeout.

Read the full sandbox guide Open verified example