claudebox/.planning/phases/01-minimal-viable-sandbox/01-CONTEXT.md

Phase 1: Minimal Viable Sandbox - Context

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

## 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.

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

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

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

## Deferred Ideas

None — discussion stayed within phase scope

---

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