# 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)

### 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 |

**Coverage:**
- v1 requirements: 31 total, v2 requirements (partial): 2
- Mapped to phases: 33
- Unmapped: 0

---
*Requirements defined: 2026-04-09*
*Last updated: 2026-04-09 after roadmap creation*