toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/phases/01-minimal-viable-sandbox/01-01-SUMMARY.md

3.5 KiB
Raw Blame History

phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established requirements-completed duration completed
01-minimal-viable-sandbox 01 infra
nix
bubblewrap
bwrap
sandbox
writeShellApplication
flake
comma-with-db
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
02-verification-and-hardening
added patterns
bubblewrap
writeShellApplication
nix-index-database
comma-with-db
clearenv-allowlist
tmpfs-root-selective-bind
exec-for-signal-passthrough
created modified
flake.nix
claudebox.sh
flake.lock
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
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
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
1min 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