# Phase 1: Minimal Viable Sandbox - Context

**Gathered:** 2026-04-09
**Status:** Ready for planning

<domain>
## Phase Boundary

Produce a working `claudebox` command via Nix flake that launches Claude Code inside a bubblewrap sandbox with environment allowlisting, filesystem isolation, secret path hiding, and on-demand tool provisioning via comma/nix. User runs `claudebox` in any project directory and gets a fully functional Claude session with secrets invisible.

</domain>

<decisions>
## Implementation Decisions

### Argument Passthrough
- **D-01:** Forward all unknown flags to `claude`. claudebox claims only its own flags (`--yes`, `--dry-run`, `--check`) and passes everything else through. No `--` separator required. `--dangerously-skip-permissions` is always injected.

### nix-index Database
- **D-02:** Use `comma-with-db` from the `nix-community/nix-index-database` flake. Self-contained — bundles the package index, no host dependency, no extra bind mount needed. DB updates when the flake input is bumped.

### Environment Variables
- **D-03:** Strict allowlist per SAND-03, plus a `CLAUDEBOX_EXTRA_ENV` escape hatch. Core allowlist always passes (HOME, PATH, TERM, EDITOR, LANG, LC_ALL, NIX_SSL_CERT_FILE, SSL_CERT_FILE, ANTHROPIC_API_KEY, USER, SHELL, XDG_RUNTIME_DIR). User can add extras at launch via `CLAUDEBOX_EXTRA_ENV="COLORTERM,NODE_OPTIONS"` — their responsibility to not leak secrets.
- **D-04:** Sandbox-generated vars (TMPDIR=/tmp, etc.) are set via `--setenv`, never read from host.

### Git Identity
- **D-05:** Generate a minimal `.gitconfig` inside the sandbox at launch time. Reads `user.name` and `user.email` from the host's git config, writes them plus `safe.directory = *` into the sandbox's `~/.gitconfig`. No host `.gitconfig` mounted — avoids credential helper, pager, and alias breakage from missing binaries.

### Claude's Discretion
- Mount ordering strategy for CWD-under-HOME (bwrap specifics)
- Exact tmpfs layout and /dev, /proc, /tmp setup
- How `--clearenv` + `--setenv` are sequenced in the bwrap invocation
- DNS resolution mount strategy (resolv.conf and its symlink targets)
- SSL cert bundle path detection

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Project Docs
- `.planning/PROJECT.md` — Core value, constraints, key decisions
- `.planning/REQUIREMENTS.md` — Full requirement list with IDs (SAND-*, TOOL-*, GIT-*, NIX-*, UX-*)
- `.planning/ROADMAP.md` — Phase 1 success criteria and requirement mapping

### Stack Research
- `CLAUDE.md` §Technology Stack — writeShellApplication, bwrap flags, comma/nix-index, flake structure, PATH construction, testing strategy

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- None — greenfield project, only CLAUDE.md exists in the repo

### Established Patterns
- None yet — Phase 1 establishes all patterns

### Integration Points
- Nix flake as entry point (`nix run`, `nix profile install`)
- `writeShellApplication` produces the claudebox script
- bwrap is the sole runtime dependency for sandboxing

</code_context>

<specifics>
## Specific Ideas

- `CLAUDEBOX_EXTRA_ENV` is comma-separated, not space-separated
- Git identity is read from host at launch time (not build time) so it works across machines
- `comma-with-db` as flake input, not a nixpkgs package

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 01-minimal-viable-sandbox*
*Context gathered: 2026-04-09*