# Requirements: claudebox

**Defined:** 2026-04-10
**Core Value:** Secrets never enter the Claude Code environment. If a secret is accessible inside the sandbox, it's a bug.

## v2.0 Requirements

Requirements for v2.0 release. Each maps to roadmap phases.

### Authentication

- [ ] **AUTH-01**: User's existing Claude subscription works inside sandbox via host `~/.claude/.credentials.json` mounted read-write
- [ ] **AUTH-02**: `ANTHROPIC_API_KEY` env var passed through when set on host (takes precedence over OAuth)

### Instance Isolation

- [ ] **INST-01**: Each project directory gets its own isolated `~/.claude` state (conversations, todos, history)
- [ ] **INST-02**: Git worktrees of the same repo share the same instance directory
- [ ] **INST-03**: Concurrent claudebox sessions in the same project are protected by flock
- [ ] **INST-04**: `--gc` command cleans up instance directories for projects that no longer exist

### Network Isolation

- [ ] **NET-01**: `--network none` fully isolates network (offline mode, Nix daemon still works via socket)
- [ ] **NET-02**: `--network inet` allows internet access but blocks LAN and Tailscale traffic
- [ ] **NET-03**: `--network full` preserves current behavior (host network, default)
- [ ] **NET-04**: `--network` CLI flag selects tier at launch
- [ ] **NET-05**: `CLAUDEBOX_NETWORK` env var sets tier (CLI flag wins if both set)

### Profiles

- [ ] **PROF-01**: Named profiles loadable via `--profile foo` or `CLAUDEBOX_PROFILE=foo` (flag wins)
- [ ] **PROF-02**: Profile defines env vars to pass through, extra mounts, and network tier
- [ ] **PROF-03**: Profiles stored as JSON at `~/.claudebox/profiles/<name>.json`
- [ ] **PROF-04**: `--list-profiles` shows available profiles
- [ ] **PROF-05**: `--show-profile <name>` displays profile contents
- [ ] **PROF-06**: Pre-launch audit extended to show active profile, network tier, and extra mounts

## Future Requirements

### Nix Package Injection

- **PKG-01**: Profile `packages` field resolved via `nix build` and added to sandbox PATH
- **PKG-02**: Package resolution cached to avoid startup latency on repeated launches

### Profile Inheritance

- **PROF-07**: Profile `extends` field to inherit from another profile

### Instance Management

- **INST-05**: Instance dir GC with dry-run mode

## Out of Scope

| Feature | Reason |
|---------|--------|
| Full nix develop devShell integration | Profile `packages` field covers 80% case; full devShell adds complexity |
| Domain-level network allowlists | Three tiers (full/inet/none) cover actual use cases |
| NixOS module form | Wrapper script derivation, not a services/programs module |
| Shareability | Personal tool first, not designed for others yet |
| Per-profile SANDBOX.md overrides | Breaks the security invariant — one SANDBOX.md for all |
| Storing secret values in profile files | Profiles reference env var names, not values |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| AUTH-01 | Phase 4 | Pending |
| AUTH-02 | Phase 4 | Pending |
| INST-01 | Phase 5 | Pending |
| INST-02 | Phase 5 | Pending |
| INST-03 | Phase 5 | Pending |
| INST-04 | Phase 5 | Pending |
| NET-01 | Phase 6 | Pending |
| NET-02 | Phase 6 | Pending |
| NET-03 | Phase 6 | Pending |
| NET-04 | Phase 6 | Pending |
| NET-05 | Phase 6 | Pending |
| PROF-01 | Phase 7 | Pending |
| PROF-02 | Phase 7 | Pending |
| PROF-03 | Phase 7 | Pending |
| PROF-04 | Phase 7 | Pending |
| PROF-05 | Phase 7 | Pending |
| PROF-06 | Phase 7 | Pending |

**Coverage:**
- v2.0 requirements: 17 total
- Mapped to phases: 17
- Unmapped: 0

---
*Requirements defined: 2026-04-10*
*Last updated: 2026-04-10 after initial definition*