toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/REQUIREMENTS.md
Christopher Mühl 6eb3b464f5 feat(05-01): register INST-01 through INST-04 requirements 
- Add Instance Isolation section after Authentication Passthrough
- INST-01: per-project isolated conversation history (no cross-contamination)
- INST-02: git worktrees share instance state via --git-common-dir
- INST-03: concurrent sessions safe (Claude Code manages own concurrency, D-13)
- INST-04: --gc removes stale instance dirs for missing project roots
- Add traceability rows mapping INST-01..04 to Phase 5
- Update coverage count from 2 to 6 v2 requirements
2026-04-13 09:01:22 +00:00

149 lines
7 KiB
Markdown
Raw Blame History

# Requirements: claudebox
**Defined:** 2026-04-09
**Core Value:** Secrets never enter the Claude Code environment
## v1 Requirements
### Sandbox Core
- [x] **SAND-01**: Wrapper script produces a `claudebox` binary via Nix `writeShellApplication`
- [x] **SAND-02**: bwrap sandbox starts with `--clearenv` — empty environment, only explicitly allowed vars pass through
- [x] **SAND-03**: Environment allowlist includes only: HOME, PATH, TERM, EDITOR, LANG, LC_ALL, NIX_SSL_CERT_FILE, SSL_CERT_FILE, ANTHROPIC_API_KEY, USER, SHELL, XDG_RUNTIME_DIR
- [x] **SAND-04**: Filesystem starts as tmpfs root — nothing from host is visible unless explicitly mounted
- [x] **SAND-05**: CWD is bind-mounted read-write inside the sandbox
- [x] **SAND-06**: `/nix/store` is mounted read-only inside the sandbox
- [x] **SAND-07**: Nix daemon socket (`/nix/var/nix/daemon-socket`) is bind-mounted for `nix shell` / comma to work
- [x] **SAND-08**: `~/.claudebox` on host is bind-mounted as `~/.claude` inside the sandbox
- [x] **SAND-09**: Secret paths are never mounted: `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config/gcloud`, age key paths, `/var/lib/tailscale`
- [x] **SAND-10**: PATH inside sandbox contains only Nix store paths: coreutils, git, curl, jq, ripgrep, fd, nix, comma, bash
- [x] **SAND-11**: Working `/tmp` (tmpfs), `/dev` (bwrap `--dev`), `/proc` (bwrap `--proc`)
- [x] **SAND-12**: DNS resolution works inside sandbox (`/etc/resolv.conf` and its symlink targets mounted)
- [x] **SAND-13**: SSL/TLS works inside sandbox (cert bundle mounted, `NIX_SSL_CERT_FILE` set)
- [x] **SAND-14**: Exit code from Claude Code passes through to the wrapper's caller
- [x] **SAND-15**: Signals (Ctrl+C) reach Claude Code via `exec` — no intermediate shell
### Tool Provisioning
- [x] **TOOL-01**: comma (`,`) is available in sandbox PATH for on-demand tool installation
- [x] **TOOL-02**: `nix shell` works inside the sandbox for installing arbitrary packages
- [x] **TOOL-03**: Newly installed Nix store paths are visible inside sandbox (live bind mount)
### User Experience
- [ ] **UX-01**: Pre-launch env audit displays all env vars being passed into the sandbox on stderr
- [ ] **UX-02**: Pre-launch env audit prompts for confirmation before proceeding
- [ ] **UX-03**: `--yes` / `-y` flag skips the env audit confirmation
- [ ] **UX-04**: `--dry-run` flag prints the full bwrap command without executing
- [ ] **UX-05**: `--check` flag verifies bwrap exists, required Nix packages are available, and `~/.claudebox` exists
- [x] **UX-06**: `claude --dangerously-skip-permissions` is always passed — the sandbox is the permission layer
### Claude Awareness
- [ ] **AWARE-01**: Default `CLAUDE.md` is created in `~/.claudebox/` on first run if not present
- [ ] **AWARE-02**: Injected CLAUDE.md tells Claude it's in a sandbox, how to use comma/nix for tools, and what's not available
### Git Support
- [x] **GIT-01**: Git works inside the sandbox with a minimal `.gitconfig` (user name/email)
- [x] **GIT-02**: `safe.directory` is configured to trust the mounted CWD
### Nix Packaging
- [x] **NIX-01**: Project is a Nix flake with `claudebox` as default package
- [x] **NIX-02**: All runtime dependencies are pinned via flake inputs
- [x] **NIX-03**: `nix run` or `nix profile install` produces a working `claudebox` command
## v2 Requirements
### Authentication Passthrough
- **AUTH-01**: `~/.claudebox/.credentials.json` (OAuth tokens) is bind-mounted read-write into the sandbox when the file exists on the host, so users do not need to re-authenticate on every launch
- **AUTH-02**: When `~/.claudebox/.credentials.json` does not exist, claudebox starts without any error or warning (silent skip)
### Instance Isolation
- **INST-01**: Each project directory has isolated conversation history — launching claudebox in two different project directories produces separate histories with no cross-contamination
- **INST-02**: Git worktrees of the same repo share instance state with the main worktree (canonical root resolved via `git rev-parse --git-common-dir`)
- **INST-03**: Two concurrent claudebox sessions in the same project do not corrupt each other's state (satisfied architecturally: Claude Code manages its own file-level concurrency within its data dir; no locking needed per D-13)
- **INST-04**: `claudebox --gc` removes instance directories for project roots that no longer exist on disk
### Network Isolation
- **NET-01**: Block LAN/Tailscale access (RFC1918 + 100.64.0.0/10) while allowing internet egress
- **NET-02**: Network namespace with controlled outbound via slirp4netns or veth pair
### Enhanced Security
- **SEC-01**: Env var leak detection — regex scan for patterns like `*KEY*`, `*TOKEN*`, `*SECRET*`
- **SEC-02**: PID namespace isolation (`--unshare-pid`)
- **SEC-03**: Git credential isolation — sandbox-specific `.gitconfig` with HTTPS-only credential helpers
### Extensibility
- **EXT-01**: Project-local tool declarations via `.claudebox.toml` or `.claudebox/tools.txt`
- **EXT-02**: Additional mount paths via `--mount-ro` / `--mount-rw` flags
- **EXT-03**: Configurable security profiles (different postures for different projects)
## Out of Scope
| Feature | Reason |
|---------|--------|
| GUI/X11/Wayland passthrough | CLI tool, no desktop integration needed |
| Audio/PulseAudio/PipeWire | No audio needed for coding agent |
| DBus access | Common sandbox escape vector, not needed |
| Seccomp syscall filtering | Threat model is data exfiltration, not privilege escalation |
| Docker/OCI wrapping | Nix+bwrap is lighter and daemonless |
| NixOS module (services/programs) | Wrapper script derivation is sufficient |
| Multi-user / shareability | Personal tool for endurance |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| SAND-01 | Phase 1 | Complete |
| SAND-02 | Phase 1 | Complete |
| SAND-03 | Phase 1 | Complete |
| SAND-04 | Phase 1 | Complete |
| SAND-05 | Phase 1 | Complete |
| SAND-06 | Phase 1 | Complete |
| SAND-07 | Phase 1 | Complete |
| SAND-08 | Phase 1 | Complete |
| SAND-09 | Phase 1 | Complete |
| SAND-10 | Phase 1 | Complete |
| SAND-11 | Phase 1 | Complete |
| SAND-12 | Phase 1 | Complete |
| SAND-13 | Phase 1 | Complete |
| SAND-14 | Phase 1 | Complete |
| SAND-15 | Phase 1 | Complete |
| TOOL-01 | Phase 1 | Complete |
| TOOL-02 | Phase 1 | Complete |
| TOOL-03 | Phase 1 | Complete |
| UX-01 | Phase 2 | Pending |
| UX-02 | Phase 2 | Pending |
| UX-03 | Phase 2 | Pending |
| UX-04 | Phase 2 | Pending |
| UX-05 | Phase 2 | Pending |
| UX-06 | Phase 1 | Complete |
| AWARE-01 | Phase 3 | Pending |
| AWARE-02 | Phase 3 | Pending |
| GIT-01 | Phase 1 | Complete |
| GIT-02 | Phase 1 | Complete |
| NIX-01 | Phase 1 | Complete |
| NIX-02 | Phase 1 | Complete |
| NIX-03 | Phase 1 | Complete |
| AUTH-01 | Phase 4 | Complete |
| AUTH-02 | Phase 4 | Complete |
| INST-01 | Phase 5 | Pending |
| INST-02 | Phase 5 | Pending |
| INST-03 | Phase 5 | Pending |
| INST-04 | Phase 5 | Pending |
**Coverage:**
- v1 requirements: 31 total, v2 requirements (partial): 6
- Mapped to phases: 33
- Unmapped: 0
---
*Requirements defined: 2026-04-09*
*Last updated: 2026-04-09 after roadmap creation*
Reference in a new issue View git blame Copy permalink