toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/REQUIREMENTS.md

3.7 KiB
Raw Blame History

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