From 4852696b95648d06a55134a9bb047644a23f59ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Fri, 10 Apr 2026 08:56:58 +0000 Subject: [PATCH] docs: create milestone v2.0 roadmap (4 phases) --- .planning/ROADMAP.md | 61 ++++++++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 24 ++++++++++------- 2 files changed, 76 insertions(+), 9 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b63d3b7..3e988d9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,6 +3,7 @@ ## Milestones - ✅ **v1.0 MVP** — Phases 1-3 (shipped 2026-04-10) +- 🚧 **v2.0 Network Isolation & Profiles** — Phases 4-7 (in progress) ## Phases @@ -17,6 +18,62 @@ Full details: [milestones/v1.0-ROADMAP.md](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**: TBD + +### 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 | @@ -24,3 +81,7 @@ Full details: [milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADMAP.md) | 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/? | 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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 9bdfca2..dd1a271 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,9 +5,9 @@ milestone_name: Network Isolation & Profiles status: active stopped_at: null last_updated: "2026-04-10" -last_activity: 2026-04-10 - Milestone v2.0 started +last_activity: 2026-04-10 - v2.0 roadmap created; phases 4-7 defined progress: - total_phases: 0 + total_phases: 4 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -20,15 +20,17 @@ progress: See: .planning/PROJECT.md (updated 2026-04-10) -**Core value:** Secrets never enter the Claude Code environment -**Current focus:** Defining requirements for v2.0 +**Core value:** Secrets never enter the Claude Code environment. If a secret is accessible inside the sandbox, it's a bug. +**Current focus:** Phase 4 — Auth Passthrough ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-04-10 — Milestone v2.0 started +Phase: 4 of 7 (Auth Passthrough) +Plan: 0 of ? in current phase +Status: Ready to plan +Last activity: 2026-04-10 — v2.0 roadmap created; phases 4-7 defined + +Progress: [███░░░░░░░] 30% (v1.0 complete; v2.0 phases 4-7 not started) ## Accumulated Context @@ -38,8 +40,10 @@ Last activity: 2026-04-10 — Milestone v2.0 started - [Phase 01]: readlink -f required to resolve NixOS profile symlinks to real nix store paths for bwrap visibility - [Phase 01]: SANDBOX_PATH built via makeBinPath in flake.nix to prevent host PATH leakage - [Phase 01]: SHELL set to nix store bash path, not /bin/bash (doesn't exist in tmpfs root) -- [Phase 01]: --shell flag added for manual sandbox debugging - [Phase 01]: SSL cert verification failure is a host-level NixOS issue, not sandbox-specific +- [v2.0 planning]: Auth mount must be read-write — OAuth token refresh writes back to .credentials.json; ro-bind causes silent EACCES +- [v2.0 planning]: Profile format will be JSON (not bash-sourced) to prevent code injection +- [v2.0 planning]: Attempt pasta sidecar first for inet tier; fall back to slirp4netns if integration is difficult ### Pending Todos @@ -47,6 +51,8 @@ None. ### Blockers/Concerns +- [Phase 6]: pasta vs slirp4netns final decision deferred to Phase 6 planning — exact CLI flags need live verification +- [Phase 6]: inet tier requires exec-to-wait refactor (background bwrap, coordinate with sidecar via --ready-fd/--exit-fd) - SSL cert verification fails system-wide (host + sandbox) — NixOS/OpenSSL issue, not claudebox ### Quick Tasks Completed