Christopher Mühl
ee686a36eb
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>
66 lines
3.6 KiB
Markdown
66 lines
3.6 KiB
Markdown
# 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*
|