toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/PROJECT.md
Christopher Mühl ee686a36eb chore: complete v1.0 MVP milestone 
Archive milestone artifacts, evolve PROJECT.md, reorganize ROADMAP.md,
write retrospective. Requirements archived to milestones/v1.0-REQUIREMENTS.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 08:05:53 +00:00

3.6 KiB
Raw Permalink Blame History

claudebox

What This Is

A Nix derivation that produces a claudebox wrapper script for Claude Code. It runs Claude inside a bubblewrap sandbox with an allowlisted environment, explicit filesystem mounts, and a minimal PATH — keeping SSH keys, GPG/age secrets, cloud tokens, and Tailscale state completely invisible to the AI agent. Includes pre-launch env audit, diagnostic modes, and sandbox-aware prompting.

Core Value

Secrets never enter the Claude Code environment. If a secret is accessible inside the sandbox, it's a bug.

Requirements

Validated

  • ✓ Wrapper script that execs claude --dangerously-skip-permissions inside a bwrap sandbox — v1.0
  • ✓ Environment allowlist: start with empty env, explicitly pass only known-safe vars — v1.0
  • ✓ Pre-launch env audit: list all env vars being passed in for user review — v1.0
  • ✓ --yes / -y flag to skip the env audit — v1.0
  • ✓ Filesystem isolation: only CWD mounted read-write, plus ~/.claudebox mapped to ~/.claude — v1.0
  • ✓ Secret paths hidden: ~/.ssh, ~/.gnupg, ~/.config/gcloud, ~/.aws, Tailscale state, age keys — v1.0
  • ✓ Minimal PATH: Nix store paths only — coreutils, git, curl, jq, ripgrep, fd, nix, comma — v1.0
  • ✓ Claude can self-install tools via nix shell or , <tool> (comma) — v1.0
  • ✓ Default SANDBOX.md injected so Claude knows its capabilities and constraints — v1.0
  • ✓ Works on endurance (NixOS desktop) — v1.0
  • ✓ --check flag for environment diagnostics — v1.0
  • ✓ --dry-run flag to print bwrap command without executing — v1.0

Active

(No active requirements — start next milestone with /gsd-new-milestone)

Out of Scope

  • Network isolation — trusting Claude Code's built-in proxy for domain allowlisting
  • NixOS module form — this is a wrapper script derivation, not a services/programs module
  • Configurable per-project profiles — v1 is one tool set, profiles come later
  • Shareability — personal tool first, not designed for others yet

Context

Shipped v1.0 with 399 LOC (350 shell + 49 Nix). Tech stack: Nix flake (writeShellApplication) + bubblewrap + comma-with-db. Runs on NixOS (endurance) with readlink -f workaround for symlink chain resolution. Non-NixOS support added via conditional /etc/static mount.

Constraints

  • Stack: Nix derivation + shell script — no Docker, no systemd, no external dependencies beyond nixpkgs
  • Sandbox: Own bwrap call — not delegating to Claude Code's --sandbox or Nix's build sandbox
  • Env model: Allowlist, not denylist — start empty, add explicitly

Key Decisions

Decision Rationale Outcome
Own bwrap over Claude's --sandbox Full control over mounts, env, namespaces ✓ Good
Env allowlist over denylist Denylist misses unknown vars; allowlist is secure by default ✓ Good
comma for tool access Claude can pull any tool on demand without pre-declaring PATH entries ✓ Good
--dangerously-skip-permissions always The bwrap sandbox IS the permission layer — Claude's prompts are redundant ✓ Good
Pre-launch env audit User reviews exactly what enters the sandbox, catches leaks before they happen ✓ Good
readlink -f for binary resolution NixOS profile symlinks aren't visible inside bwrap; resolve to real store paths ✓ Good
Claude Code via nix-claude-code flake ryoppippi/nix-claude-code, not host PATH ✓ Good
SANDBOX.md as separate file with @import Keeps user CLAUDE.md clean, sandbox instructions always fresh ✓ Good

Last updated: 2026-04-10 after v1.0 milestone