claudebox/.planning/ROADMAP.md

Roadmap: claudebox

Milestones

• ✅ v1.0 MVP — Phases 1-3 (shipped 2026-04-10)
• 🚧 v2.0 Network Isolation & Profiles — Phases 4-7 (in progress)

Phases

✅ v1.0 MVP (Phases 1-3) — SHIPPED 2026-04-10

• Phase 1: Minimal Viable Sandbox (2/2 plans) — bwrap sandbox with clearenv, env allowlist, filesystem isolation, secret hiding, tool provisioning
• Phase 2: Env Audit and CLI Polish (2/2 plans) — --check, --dry-run, env audit display with masking, confirmation prompt
• Phase 3: Sandbox-Aware Prompting (1/1 plan) — SANDBOX.md generation, CLAUDE.md import management

Full details: milestones/v1.0-ROADMAP.md

🚧 v2.0 Network Isolation & Profiles (In Progress)

Milestone Goal: Add tiered network isolation, per-project instance isolation, named profiles, and host auth passthrough so Claude can authenticate, work in project-scoped history, operate at controlled network exposure, and run under reusable configuration profiles.

• Phase 4: Auth Passthrough — Mount host Claude credentials read-write so subscription and API key access work inside the sandbox
• Phase 5: Per-Project Instance Isolation — Scope conversation history and state to each project directory automatically
• Phase 6: Tiered Network Isolation — Add none/inet/full network tiers selectable at launch
• Phase 7: Named Profiles — Load named configuration profiles that set env vars, mounts, and network tier

Phase Details

Phase 4: Auth Passthrough

Goal: Claude Code inside the sandbox can authenticate using the host subscription or API key Depends on: Phase 3 Requirements: AUTH-01, AUTH-02 Success Criteria (what must be TRUE):

1. Running claudebox with an active Claude subscription succeeds without re-authentication
2. OAuth token refresh completes silently — credentials file is updated and the session continues
3. When ANTHROPIC_API_KEY is set on the host, it is passed into the sandbox and takes precedence over OAuth Plans: 1 plan

Plans:

• 04-01-PLAN.md — Credential mount + audit redesign (unified env list, Mounts section, Network section)

Phase 5: Per-Project Instance Isolation

Goal: Each project directory has its own isolated Claude state so conversation history, todos, and settings do not bleed between projects Depends on: Phase 4 Requirements: INST-01, INST-02, INST-03, INST-04 Success Criteria (what must be TRUE):

1. Launching claudebox in two different project directories produces two separate conversation histories with no cross-contamination
2. Launching claudebox from a git worktree shares instance state with the main worktree of the same repo
3. Two concurrent claudebox sessions in the same project do not corrupt each other's state
4. Running claudebox --gc removes instance directories for project roots that no longer exist on disk Plans: TBD

Phase 6: Tiered Network Isolation

Goal: Users can select a network access tier at launch to control whether Claude has no network, internet-only, or full host network access Depends on: Phase 5 Requirements: NET-01, NET-02, NET-03, NET-04, NET-05 Success Criteria (what must be TRUE):

1. --network none (or CLAUDEBOX_NETWORK=none) starts a session with no network access; DNS and all TCP connections fail inside the sandbox while the Nix daemon socket remains usable
2. --network inet starts a session where internet hostnames resolve and connections succeed, but LAN addresses and Tailscale IPs are unreachable
3. --network full (the default) preserves existing behavior with full host network access
4. When both CLAUDEBOX_NETWORK and --network are set, the CLI flag wins Plans: TBD UI hint: no

Phase 7: Named Profiles

Goal: Users can define named profiles that package env var passthrough, extra mounts, and network tier into a reusable configuration loaded by name at launch Depends on: Phase 6 Requirements: PROF-01, PROF-02, PROF-03, PROF-04, PROF-05, PROF-06 Success Criteria (what must be TRUE):

1. claudebox --profile foo loads ~/.claudebox/profiles/foo.json and applies its env vars, mounts, and network tier for the session
2. CLAUDEBOX_PROFILE=foo activates a profile when no --profile flag is given; --profile wins when both are set
3. claudebox --list-profiles prints all profiles found under ~/.claudebox/profiles/
4. claudebox --show-profile foo prints the contents of the named profile
5. The pre-launch env audit displays the active profile name, resolved network tier, and any extra mounts added by the profile Plans: TBD

Progress

Phase	Milestone	Plans Complete	Status	Completed
1. Minimal Viable Sandbox	v1.0	2/2	Complete	2026-04-09
2. Env Audit and CLI Polish	v1.0	2/2	Complete	2026-04-09
3. Sandbox-Aware Prompting	v1.0	1/1	Complete	2026-04-10
4. Auth Passthrough	v2.0	0/1	Not started	-
5. Per-Project Instance Isolation	v2.0	0/?	Not started	-
6. Tiered Network Isolation	v2.0	0/?	Not started	-
7. Named Profiles	v2.0	0/?	Not started	-