---
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*