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
• 16. The integrity guard’s re-stamp trust anchor must live outside the workspace
• 17. Remove just promote; the sandbox keeps one auditable home
• 18. One shadow, many agents: wrap Codex the way we wrap Claude
• 19. Add Pi and an explicit single-port localhost relay
• 20. Relay a set of loopback ports to every agent
• 21. Relay fixed OAuth callback ports into the jail
• 23. A PyPI wheel as the front door: uvx claude-sandbox
• 24. Ship agent skills by read-only bind, not into the user’s config
• 25. Share ~/.agents/skills read-write with every agent

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