# Roadmap: claudebox

## Milestones

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

## Phases

<details>
<summary>✅ v1.0 MVP (Phases 1-3) — SHIPPED 2026-04-10</summary>

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

Full details: [milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADMAP.md)

</details>

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