Architectural Decision Records

Architectural decisions are made throughout a project’s lifetime. As a way of keeping track of these decisions, we record them in Architecture Decision Records (ADRs) listed below.

These ADRs record the why behind the sandbox’s shape, in the threat model’s own terms. The claude-sandbox skill (.claude/skills/claude-sandbox/SKILL.md) is the operational companion: it records the same invariants as regressions to refuse for an agent editing the code.

• 1. Record architecture decisions
• 2. A credential-isolation tool, not a general-purpose sandbox
• 3. Live in a standalone repo, extracted from python-copier-template
• 4. Isolate with bwrap: drop all capabilities, scrub the environment, invert /root to default-deny
• 5. Leave network egress open; egress filtering is out of scope
• 6. Scope credentials to the container; re-paste PATs on every rebuild
• 7. Redirect git to a curated gitconfig rather than masking the host’s
• 8. Bash-only: no Python package, uv, or pytest
• 9. Relocate the real Claude binary off PATH so the shadow always wins
• 10. just promote copies by value and never edits devcontainer.json
• 11. Split the home re-binds by XDG category
• 12. Treat the read-write workspace as untrusted: default to $PWD, source config from /etc
• 13. Deliver the integrity guard globally via managed-settings
• 14. Keep the integrity-check surfaces separate and self-contained
• 15. Jail Claude’s egress in a per-process netns with a routing allowlist

For more on ADRs see this blog by Michael Nygard. To add one, copy decisions/COPYME to the next free NNNN-slug.md.