73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# Roadmap: claudebox
|
|
|
|
## Overview
|
|
|
|
claudebox is a Nix-packaged bwrap sandbox wrapper for Claude Code. The roadmap moves from a working sandbox (Phase 1) through CLI polish (Phase 2) to sandbox-aware prompting (Phase 3). Phase 1 is the bulk of the work -- once Claude runs inside bwrap with env isolation, filesystem isolation, and tool provisioning, the remaining phases add UX and developer experience improvements.
|
|
|
|
## Phases
|
|
|
|
**Phase Numbering:**
|
|
- Integer phases (1, 2, 3): Planned milestone work
|
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
|
|
|
|
Decimal phases appear between their surrounding integers in numeric order.
|
|
|
|
- [ ] **Phase 1: Minimal Viable Sandbox** - Working claudebox command that launches Claude in bwrap with full isolation and tool provisioning
|
|
- [ ] **Phase 2: Env Audit and CLI Polish** - Pre-launch env review, --yes, --dry-run, and --check flags
|
|
- [ ] **Phase 3: Sandbox-Aware Prompting** - Injected CLAUDE.md so Claude knows its capabilities and constraints
|
|
|
|
## Phase Details
|
|
|
|
### Phase 1: Minimal Viable Sandbox
|
|
**Goal**: User can run `claudebox` in any project directory and get a fully functional Claude Code session with secrets invisible
|
|
**Depends on**: Nothing (first phase)
|
|
**Requirements**: SAND-01, SAND-02, SAND-03, SAND-04, SAND-05, SAND-06, SAND-07, SAND-08, SAND-09, SAND-10, SAND-11, SAND-12, SAND-13, SAND-14, SAND-15, TOOL-01, TOOL-02, TOOL-03, GIT-01, GIT-02, NIX-01, NIX-02, NIX-03, UX-06
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Running `nix run` or `nix profile install` produces a working `claudebox` command
|
|
2. `claudebox` launches Claude Code inside bwrap; `env` inside the sandbox shows only allowlisted variables (no SSH_AUTH_SOCK, AWS_PROFILE, etc.)
|
|
3. Secret paths (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, age keys, /var/lib/tailscale) are not visible inside the sandbox
|
|
4. Claude can run `curl https://example.com`, `git status`, `, jq --help` (comma), and `nix shell nixpkgs#python3 -c python3 --version` inside the sandbox
|
|
5. Ctrl+C terminates the session cleanly; exit code from Claude passes through to the caller
|
|
**Plans:** 2 plans
|
|
|
|
Plans:
|
|
- [x] 01-01-PLAN.md -- Create flake.nix and claudebox.sh with complete bwrap sandbox
|
|
- [x] 01-02-PLAN.md -- Build verification and manual sandbox smoke test
|
|
|
|
### Phase 2: Env Audit and CLI Polish
|
|
**Goal**: User can review exactly what enters the sandbox before launch, and has diagnostic tools for troubleshooting
|
|
**Depends on**: Phase 1
|
|
**Requirements**: UX-01, UX-02, UX-03, UX-04, UX-05
|
|
**Success Criteria** (what must be TRUE):
|
|
1. Running `claudebox` without `--yes` prints all env vars being passed into the sandbox and prompts for confirmation before proceeding
|
|
2. Running `claudebox --yes` or `claudebox -y` skips the env audit and launches immediately
|
|
3. Running `claudebox --dry-run` prints the full bwrap command without executing it
|
|
4. Running `claudebox --check` reports whether bwrap exists, required Nix packages are available, and ~/.claudebox exists
|
|
**Plans:** 2 plans
|
|
|
|
Plans:
|
|
- [x] 02-01-PLAN.md -- Refactor flag parsing, add --check and --dry-run modes
|
|
- [x] 02-02-PLAN.md -- Env audit display with grouping, masking, and confirmation prompt
|
|
|
|
### Phase 3: Sandbox-Aware Prompting
|
|
**Goal**: Claude inside the sandbox knows it is sandboxed, how to install tools, and what is unavailable
|
|
**Depends on**: Phase 1
|
|
**Requirements**: AWARE-01, AWARE-02
|
|
**Success Criteria** (what must be TRUE):
|
|
1. First run of `claudebox` creates a default CLAUDE.md in ~/.claudebox/ if none exists
|
|
2. The injected CLAUDE.md tells Claude it is in a bwrap sandbox, how to use comma (`, <tool>`) and `nix shell` for tool installation, and that SSH/GPG/cloud credentials are unavailable
|
|
**Plans:** 1 plan
|
|
|
|
Plans:
|
|
- [ ] 03-01-PLAN.md -- Add SANDBOX.md generation and CLAUDE.md import management
|
|
|
|
## Progress
|
|
|
|
**Execution Order:**
|
|
Phases execute in numeric order: 1 -> 2 -> 3
|
|
|
|
| Phase | Plans Complete | Status | Completed |
|
|
|-------|----------------|--------|-----------|
|
|
| 1. Minimal Viable Sandbox | 2/2 | Complete | - |
|
|
| 2. Env Audit and CLI Polish | 0/2 | Planned | - |
|
|
| 3. Sandbox-Aware Prompting | 0/1 | Not started | - |
|