git:20260919.6cf18f7 to git:20260919.04aa2b5

---

name: sandbox

description: Run an autonomous or long-running agent loop with the filesystem and network fenced: the built-in sandbox with network off, or a container with the worktree mounted. Use before any unattended loop, before `execute` autonomy on an unfamiliar repo, and whenever a task pulls untrusted input.

---

# Fence the loop

A permission mode decides whether a call runs. A sandbox decides what a command can reach once it

is running, and the OS enforces that on every child process. An unattended loop needs the second

kind: nobody is at the prompt to answer for the first.

It "runs on macOS, Linux, and WSL2. Native Windows is not supported"; Linux and WSL2 need

`bubblewrap` and `socat` installed first. Put this in `~/.claude/settings.json` to cover every

project; the `/sandbox` panel writes `enabled` to `.claude/settings.local.json` for one project.

```json

{

"sandbox": {

"enabled": true,

"failIfUnavailable": true,

"allowUnsandboxedCommands": false,

"network": { "allowedDomains": [], "strictAllowlist": true },

"filesystem": { "denyRead": ["~/.ssh", "~/.aws", "~/.config/gh"] }

}

}

```

`strictAllowlist` over an empty `allowedDomains` is network off: Claude Code then "denies sandboxed

commands access to any host outside the allowlist instead of prompting". Only user, managed and

`--settings` settings set it; a repository's own file cannot. The deny entries are load-bearing —

the default read policy covers the whole disk, and "this default still allows reading credential

files such as `~/.aws/credentials` and `~/.ssh/`." Add `sandbox.credentials.envVars` entries with

`"mode": "deny"` to unset tokens for sandboxed commands too. `failIfUnavailable` makes a missing

dependency a hard stop rather than a silent unsandboxed fallback, and `allowUnsandboxedCommands:

false` removes the retry-outside escape hatch. Subagents inherit the session's sandbox; commands

you type at the `!` prompt do not.

For one session, writing no file: `claude --settings '{"sandbox":{"enabled":true}}'`. Confirm with

`/sandbox`: the **Config** tab shows the resolved settings, and a **Dependencies** tab appearing

means a package is missing. A prompt titled "Bash command (unsandboxed)" is the signal a command

left the boundary. Keys and defaults: https://code.claude.com/docs/en/sandboxing

## A container

Harder boundary, coarser tooling. Mount the worktree and nothing else, stay non-root, and let the

container be the isolation — do not nest the built-in sandbox inside it.

```bash

docker run --rm -it --network none \

--user "$(id -u):$(id -g)" \

-v "$PWD:/work" -w /work \

-v "$HOME/.claude:/config:ro" -e CLAUDE_CONFIG_DIR=/config -e ANTHROPIC_API_KEY \

<image-with-the-cli> claude --dangerously-skip-permissions -p "<the loop prompt>"

```

`podman` substitutes unchanged. What breaks, in order: `--network none` cuts the model API too, so

as written this runs only against a local model — for a loop that must reach the API, allow that

one host and nothing else and the shape holds. Then web search and fetch, every MCP server reached

over the network, and every package install; a read-only config mount blocks session state and

credential writes, so auth arrives by environment variable. Losing all of it is the point when the

task parses input you did not write: a path the loop lacks cannot be talked into opening.

## Which one

Built-in sandbox for daily work: a settings change, every tool still works, the OS still enforces

the boundary. Container for a loop that runs while you sleep, a repo whose build scripts you have

not read, or anything handling untrusted content. Neither isolates branches — run inside a

worktree as well, per the `worktree-per-agent` skill.