claude-sandbox

name

claude-sandbox

description

Architecture decisions and historical reversals for this repo's bwrap-based Claude sandbox. Covers real claude off PATH, container-scoped PATs, Ubuntu-24.04 CI bwrap workarounds, dogfood ≈ guest, the `just promote` three-layer model (no JSONC editing), and two walked-back paths (Python orchestration; embedding in python-copier-template). Surface before edits to `.devcontainer/claude-sandbox/{claude-shadow,install.sh,promote.sh}`, `install`, `tests/`, `.github/workflows/ci.yml`, or `.claude/commands/verify-sandbox.md`; or before any suggestion to re-introduce Python tooling, embed in python-copier-template, persist gh/glab PATs across containers, or auto-edit JSONC devcontainer.json.

claude-sandbox

Project-specific architecture decisions. The code documents what; this skill documents why and what regressions to refuse. Threat model: README-CLAUDE.md; live verification: /verify-sandbox (.claude/commands/verify-sandbox.md).

Invariant 1 — plain claude MUST resolve to the shadow

Anthropic's curl install.sh drops the real binary at ~/.local/bin/claude AND prepends $HOME/.local/bin to the user's shell rc. After the next shell, which claude resolves past the bwrap shadow at /usr/local/bin/claude → sandbox escape via plain claude.

install_claude_binary fixes this by relocating the real binary to /usr/libexec/claude-sandbox/claude (off the user's PATH). The shadow binds it back to ~/.local/bin/claude inside the sandbox so Claude's installMethod=native self-check still sees the conventional path.

Refuse as regressions:

• Any "simplification" that skips the relocate-after-curl step.
• Removing the unconditional bind-back of ~/.local/bin/claude inside the sandbox — the dest is created on the in-sandbox tmpfs $HOME, so don't gate it on the host file existing.
• tests/bwrap_argv.sh scenarios 1 & 4a guard the bind pair; update both if you change the bind.

Acceptable swap: if Anthropic adds --no-modify-path, drop the relocate — provided plain claude still cannot resolve past /usr/local/bin/claude.

Invariant 2 — PATs are container-scoped; just gh-auth per rebuild is deliberate

The re-paste-on-rebuild ceremony for gh / glab PATs is the cost of keeping blast radius small: fine-grained PATs typically cover multiple repos, so any path mounted across devcontainers would let a compromised session reach every repo the PAT touches.

~/.claude and ~/.claude.json are cross-container (via link_terminal_config symlinks) because they hold one Claude login, not repo-scoped credentials. Don't conflate the two.

Refuse as regressions:

• New persistent-credential mounts (volume, bind, anywhere) for gh or glab PATs.
• Re-purposing the (currently deleted) /cache Docker volume for tokens. Restoring /cache for caches is fine; for tokens, not.

If a future request says "stop re-pasting the PAT" — surface this tradeoff before implementing the shortcut.

Invariant 3 — bwrap on Ubuntu 24.04 GitHub runners needs three workarounds

ubuntu-latest ships configured in ways that break bwrap. The failure modes cascade in this order:

1. setting up uid map: Permission denied — kernel.apparmor_restrict_unprivileged_userns=1 is the runner default. Relax the sysctl and install an unconfined AppArmor profile for /usr/bin/bwrap.
2. /run/secrets doesn't exist — sandbox does --tmpfs /run/secrets; sudo mkdir -p /run/secrets first.
3. $GITHUB_WORKSPACE lives under $HOME=/home/runner — path-positional checks that assert "$HOME contains only X" trip on the workspace bind. export HOME=/tmp/sandbox-home before the bwrap step (+ mkdir -p "$HOME/.claude" "$HOME/.cache").

All three are required, in order. .github/workflows/ci.yml applies them — five push-and-iterate cycles to land this; don't re-discover.

Design principle — keep dogfood ≈ guest

The repo's own devcontainer (dogfood) and a git clone + ./install inside any other devcontainer (guest) should go through the same setup path. Prefer install.sh over devcontainer.json / postCreate.sh / initializeCommand.sh when a fix can live in either — guest devcontainers then get it for free, and the audit surface stays single-track.

Sample: per-file binds for /root/.claude{,.json} were dropped once link_terminal_config covered both paths uniformly; only the shared /user-terminal-config bind remains in devcontainer.json.

Refuse as regressions: dogfood-only postCreate / initializeCommand work, or devcontainer.json mounts that could have been done in install.sh. Ask "would this work for a clone+install inside an unrelated devcontainer?" — if not, push it into install.sh.

Design principle — just promote does three layers, never edits JSONC

just promote <target> (PR #20, issue #18) makes a target workspace a self-sufficient claude-sandbox host:

1. Curated .claude/ — commands, skills, hooks, statusline, plus wire_settings_{hook,statusline} against the target's settings.json.
2. Install machinery — .devcontainer/claude-sandbox/{install.sh, claude-shadow, promote.sh} + root justfile. The justfile is shipped verbatim, so its recipes must all be promote-target-safe; source-repo-only recipes (test, upgrade, verify) were dropped for this reason. The root install shim is not copied; it's the source repo's manual-UX entry (./install), not a target workflow.
3. .devcontainer/postCreate.sh running bash .devcontainer/claude-sandbox/install.sh (created if absent, idempotently appended otherwise). Promote then prints a one-line postCreateCommand snippet for the user to paste into devcontainer.json — we do not edit it.

Refuse as a regression: auto-editing devcontainer.json. It's JSONC in the wild and comment-preserving structured edits need either ~50 lines of awk (string/block-comment state-tracking) or a node/python lib dependency — both rejected in PR #20. The user knows whether they've wired the line or need to chain it. "Strip and re-insert comments" isn't simpler either — re-insert needs stable anchors that survive the edit. Print the snippet; trust them.

Two intentional don't-update edges in re-promote — the only gaps in the "re-promote = full sync" mental model:

• wire_settings_statusline is create-if-absent. An existing .statusLine (ours or the user's) is left alone.
• wire_postcreate_script only checks whether bash install is on any line of postCreate.sh. The file body is never rewritten if the file exists.

Everything else propagates via install_file's cmp -s overwrite-on-diff.

Source-guard pattern: install.sh ends with [ "${BASH_SOURCE[0]}" = "$0" ] && main "$@" so promote.sh can source install.sh to reuse install_file + wire_settings_* without re-running main. Don't remove the guard.

Considered alternative — postCreate references shared clone (declined)

A natural-sounding refinement: drop layer 2 of promote (the install-machinery copy) and have the target's postCreate.sh invoke install.sh directly from the canonical clone, e.g. bash /user-terminal-config/claude-sandbox/.devcontainer/claude-sandbox/install.sh. Drift auto-resolves on git pull of the canonical clone; audit surface stays single-tracked. (Variant: do this from bashrc — even weaker, since install.sh does root-level work, see invariant 1.)

Declined because it sacrifices two properties promote-by-copy deliberately optimises for:

• Self-sufficiency. git clone <target> && ./install works in any devcontainer. Reference-by-path requires the shared clone on every host — breaks CI runners, clean VMs, collaborators with different layouts.
• Frozen audit surface. Promote-by-copy means "what ran is what's at this SHA in this repo." Reference-by-path means what runs depends on whichever HEAD the shared clone happens to be at. Drift you can see beats drift you can't.

If a future request says "just point postCreate at the shared clone", surface this tradeoff before agreeing. Acceptable compromise if explicitly asked: an opt-in recipe (e.g. just wire-postcreate-shared) alongside today's frozen-copy default. Do not "retain both mechanisms and keep them synced" — that's the synchronisation debt Reversal 2 walked away from.

Historical reversals — raise before re-treading

Two paths walked back. If a change suggests either, surface the history and re-justify against the underlying principle — the sandbox's surface must stay small enough to audit in one read — before proceeding.

Reversal 1 — Python orchestration

Trajectory: embedded bash → standalone bash → Python package + typer CLI → bash-only (commits 25e67ce, a35b8ee, then bf65407 "feat: bash-only rewrite — drop Python package, self-contained shadow", 2026-05-12, issue #14 / PR #15).

The tool is fundamentally one bash function building a bwrap argv. A ~110 KB Python package (pyproject, uv lockfile, pytest scaffolding, 37 unit tests, typer CLI) made the security-critical bits harder to audit across multiple modules. Bash-only is ~80 lines shadow + ~80 lines installer.

Refuse without justification:

• "Let's add a small Python CLI for nicer error messages / config / arg parsing."
• "Let's bring back pytest / uv / a src/ package — it's only a little code."
• Anything that re-introduces pyproject.toml, uv.lock, src/claude_sandbox/, or test_*.py.

Root CLAUDE.md says "Bash-only. No Python package, no uv, no pytest — don't add them back." This skill explains the why.

Reversal 2 — extracted from python-copier-template

The sandbox originally lived embedded in python-copier-template as .devcontainer/claude-sandbox.sh (a single bash script using unshare -m + tmpfs overlays). Extracted because:

• A security tool needs one canonical, audit-friendly home, not a templated copy in every project.
• The bwrap-based defences (--cap-drop ALL, --clearenv allow-list, strict-under-/root inversion, NO_NEW_PRIVS, …) replace the older unshare -m and would be awkward inside a per-project template.
• A standalone repo gets a versioned release surface, its own CI, and /verify-sandbox as a first-class command.

/workspaces/python-copier-template/.devcontainer/claude-sandbox.sh exists as prior art but is not maintained.

Refuse without justification:

• Adding a template/ directory or copier.yml.
• "Let's keep a copy synced into python-copier-template" — the template should consume this repo, not embed it.

Diagnostic discipline — silent in-sandbox check failures

When a check inside the sandbox fails silently (subprocess swallows stdout/stderr), inject a debug INNER step that runs the same body verbatim and prints its output before exec'ing the real verifier. The original Check 03 silent failure was unsolvable until we printed extras directly — --bind-try /dev/null masks themselves create entries under $HOME (the spec hadn't whitelisted them). One printf beats hours of guessing from outside.

Diagnostic discipline — bind-mount vs runtime tmpfs write

When unexpected entries appear inside the sandbox (typically under $HOME or $HOME/.config), first determine whether they're a host bind-mount leak or a sandboxed-process tmpfs write. The remediations are completely different.

# Bind from the host?
grep " /root/.config/<thing> " /proc/self/mountinfo
# stat -c '%D' compares device IDs — tmpfs entries share /root's dev.
stat -c '%n: dev=%D inode=%i' /root /root/.config/<thing>

No mountinfo entry + same dev as /root → tmpfs write by sandboxed code (a feature self-registering). Fix upstream by disabling the feature, not by widening the allow-list. Mountinfo entry → genuine inversion leak; tighten the bwrap argv.

Concrete miss (2026-05): Chrome NativeMessagingHosts dirs under ~/.config/ — initially flagged as a bind leak; mountinfo showed no bind. It was Claude Code's startup write registering the browser extension. Fix: --no-chrome injection in the shadow, check 03 stayed strict.

Invariant 4 — config is host-global at /etc, never read from the workspace

claude-shadow reads its config from /etc/claude-sandbox.conf (CONFIG_PATH), placed by install.sh's install_conf from the clone's .devcontainer/claude-sandbox.conf and re-stamped on every rebuild via postCreate. It is NOT read from $PWD/.devcontainer/claude-sandbox.conf anymore (that call site moved in PR for the global-conf change).

Two reasons, one load-bearing for the threat model:

• Security (the real reason). $PWD is the workspace, bound rw into the sandbox. A per-workspace conf is attacker-writable from inside the jail: a compromised session could write allow-write = / (or workspace-root = /) and the next launch would --bind it rw, a cross-session breakout. /etc is not in the rw bind set.
• Ergonomics. One global conf means allow-write = /cache (uv) and friends apply to claude in every workspace with nothing added to individual repos. Edit the clone conf + re-run ./install (a rebuild does it via postCreate) to apply.

parse_config still takes the path as $1 (tests pass a fixture); only the launch-time call site is pinned to CONFIG_PATH. Env vars (CLAUDE_SANDBOX_*) still override per session. just promote still ships a starter conf into a promoted target's .devcontainer/, whose own install.sh reads it into /etc (keeps promoted hosts self-sufficient).

Refuse as regressions:

• Any change that reads the conf from $PWD, the workspace, or any sandbox-rw path. The conf source must stay outside the jail's rw set.
• "Make allow-write per-repo again so projects can opt in" reopens the cross-session bind-escalation vector. Per-session env vars are the supported override; the global conf is the only file.
• verify-sandbox check 18 guards that the installed shadow reads /etc and has no $PWD/.devcontainer read. tests/bwrap_argv.sh scenario 8b guards that $VIRTUAL_ENV/bin is appended (not prepended) to PATH, and the harness unsets the runner's VIRTUAL_ENV/UV_* so the suite is deterministic inside an activated venv. Keep all three.

Where things live

Concern	File
bwrap argv construction	.devcontainer/claude-sandbox/claude-shadow
Installer (relocate + wire)	.devcontainer/claude-sandbox/install.sh
Promote orchestrator	.devcontainer/claude-sandbox/promote.sh
Root-shim installer entry	install
bwrap argv unit tests	tests/bwrap_argv.sh
End-to-end install smoke test	tests/smoke.sh
Promote smoke test	tests/promote.sh
CI workflow	.github/workflows/ci.yml
Live verification spec	.claude/commands/verify-sandbox.md
Pre-prompt gate hook	.claude/hooks/sandbox-check.sh
Threat model + binds rationale	README-CLAUDE.md
Recipes (promote, gh-auth, …)	justfile (shipped verbatim by just promote)

Touching any of these → re-read this skill first.