95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
---
|
|
phase: 01-minimal-viable-sandbox
|
|
plan: 01
|
|
subsystem: infra
|
|
tags: [nix, bubblewrap, bwrap, sandbox, writeShellApplication, flake, comma-with-db]
|
|
|
|
requires: []
|
|
provides:
|
|
- "claudebox command via nix build/run"
|
|
- "bwrap sandbox with clearenv + env allowlist"
|
|
- "filesystem isolation with secret path hiding"
|
|
- "git identity forwarding via generated .gitconfig"
|
|
- "comma/nix tool provisioning inside sandbox"
|
|
affects: [02-verification-and-hardening]
|
|
|
|
tech-stack:
|
|
added: [bubblewrap, writeShellApplication, nix-index-database, comma-with-db]
|
|
patterns: [clearenv-allowlist, tmpfs-root-selective-bind, exec-for-signal-passthrough]
|
|
|
|
key-files:
|
|
created: [flake.nix, claudebox.sh, flake.lock]
|
|
modified: []
|
|
|
|
key-decisions:
|
|
- "Claude Code discovered from host PATH at runtime, not bundled as runtimeInput"
|
|
- "Sandbox-generated vars (TMPDIR, XDG_RUNTIME_DIR) never read from host"
|
|
- "CLAUDEBOX_EXTRA_ENV comma-separated escape hatch for user-added env vars"
|
|
|
|
patterns-established:
|
|
- "writeShellApplication + builtins.readFile: keep shell script separate for syntax highlighting and independent shellcheck"
|
|
- "clearenv + setenv: start empty, allowlist explicitly"
|
|
- "tmpfs root + selective bind-mounts: nothing visible unless explicitly mounted"
|
|
- "exec bwrap: no intermediate shell, signals propagate, exit code passes through"
|
|
|
|
requirements-completed: [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]
|
|
|
|
duration: 1min
|
|
completed: 2026-04-09
|
|
---
|
|
|
|
# Phase 1 Plan 01: Nix Flake and Sandbox Script Summary
|
|
|
|
**Nix flake with writeShellApplication producing claudebox wrapper that runs Claude Code inside bwrap with clearenv, env allowlist, tmpfs root, secret hiding, git identity forwarding, and comma/nix tool access**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** ~1 min
|
|
- **Started:** 2026-04-09T09:10:55Z
|
|
- **Completed:** 2026-04-09T09:12:10Z
|
|
- **Tasks:** 2
|
|
- **Files created:** 3 (flake.nix, claudebox.sh, flake.lock)
|
|
|
|
## Accomplishments
|
|
- Nix flake with 11 runtimeInputs (bubblewrap, coreutils, git, curl, jq, ripgrep, fd, nix, comma-with-db, bash, nodejs) and nix-index-database flake input
|
|
- Shell script with complete bwrap invocation: clearenv, env allowlist with CLAUDEBOX_EXTRA_ENV escape hatch, tmpfs root, selective bind-mounts, git identity generation, secret path exclusion
|
|
- `nix build` succeeds -- derivation builds and passes shellcheck
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Create flake.nix** - `0ed2d33` (feat)
|
|
2. **Task 2: Create claudebox.sh** - `51dba04` (feat)
|
|
3. **flake.lock generated by nix flake check** - `26bdf36` (chore)
|
|
|
|
## Files Created/Modified
|
|
- `flake.nix` - Nix flake with writeShellApplication, all runtimeInputs, nix-index-database input
|
|
- `claudebox.sh` - bwrap sandbox script with clearenv, env allowlist, filesystem isolation, git identity
|
|
- `flake.lock` - Pinned nixpkgs and nix-index-database versions
|
|
|
|
## Decisions Made
|
|
None - followed plan as specified.
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
None.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- claudebox builds successfully via `nix build`
|
|
- Ready for 01-02 (verification and manual testing)
|
|
- Requires `claude` to be available on host PATH for runtime use
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All 3 files exist. All 3 commits verified.
|
|
|
|
---
|
|
*Phase: 01-minimal-viable-sandbox*
|
|
*Completed: 2026-04-09*
|