toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/REQUIREMENTS.md

6.2 KiB
Raw Blame History

Requirements: claudebox

Defined: 2026-04-09 Core Value: Secrets never enter the Claude Code environment

v1 Requirements

Sandbox Core

  • SAND-01: Wrapper script produces a claudebox binary via Nix writeShellApplication
  • SAND-02: bwrap sandbox starts with --clearenv — empty environment, only explicitly allowed vars pass through
  • SAND-03: Environment allowlist includes only: HOME, PATH, TERM, EDITOR, LANG, LC_ALL, NIX_SSL_CERT_FILE, SSL_CERT_FILE, ANTHROPIC_API_KEY, USER, SHELL, XDG_RUNTIME_DIR
  • SAND-04: Filesystem starts as tmpfs root — nothing from host is visible unless explicitly mounted
  • SAND-05: CWD is bind-mounted read-write inside the sandbox
  • SAND-06: /nix/store is mounted read-only inside the sandbox
  • SAND-07: Nix daemon socket (/nix/var/nix/daemon-socket) is bind-mounted for nix shell / comma to work
  • SAND-08: ~/.claudebox on host is bind-mounted as ~/.claude inside the sandbox
  • SAND-09: Secret paths are never mounted: ~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud, age key paths, /var/lib/tailscale
  • SAND-10: PATH inside sandbox contains only Nix store paths: coreutils, git, curl, jq, ripgrep, fd, nix, comma, bash
  • SAND-11: Working /tmp (tmpfs), /dev (bwrap --dev), /proc (bwrap --proc)
  • SAND-12: DNS resolution works inside sandbox (/etc/resolv.conf and its symlink targets mounted)
  • SAND-13: SSL/TLS works inside sandbox (cert bundle mounted, NIX_SSL_CERT_FILE set)
  • SAND-14: Exit code from Claude Code passes through to the wrapper's caller
  • SAND-15: Signals (Ctrl+C) reach Claude Code via exec — no intermediate shell

Tool Provisioning

  • TOOL-01: comma (,) is available in sandbox PATH for on-demand tool installation
  • TOOL-02: nix shell works inside the sandbox for installing arbitrary packages
  • TOOL-03: Newly installed Nix store paths are visible inside sandbox (live bind mount)

User Experience

  • UX-01: Pre-launch env audit displays all env vars being passed into the sandbox on stderr
  • UX-02: Pre-launch env audit prompts for confirmation before proceeding
  • UX-03: --yes / -y flag skips the env audit confirmation
  • UX-04: --dry-run flag prints the full bwrap command without executing
  • UX-05: --check flag verifies bwrap exists, required Nix packages are available, and ~/.claudebox exists
  • UX-06: claude --dangerously-skip-permissions is always passed — the sandbox is the permission layer

Claude Awareness

  • AWARE-01: Default CLAUDE.md is created in ~/.claudebox/ on first run if not present
  • AWARE-02: Injected CLAUDE.md tells Claude it's in a sandbox, how to use comma/nix for tools, and what's not available

Git Support

  • GIT-01: Git works inside the sandbox with a minimal .gitconfig (user name/email)
  • GIT-02: safe.directory is configured to trust the mounted CWD

Nix Packaging

  • NIX-01: Project is a Nix flake with claudebox as default package
  • NIX-02: All runtime dependencies are pinned via flake inputs
  • NIX-03: nix run or nix profile install produces a working claudebox command

v2 Requirements

Authentication Passthrough

  • AUTH-01: ~/.claudebox/.credentials.json (OAuth tokens) is bind-mounted read-write into the sandbox when the file exists on the host, so users do not need to re-authenticate on every launch
  • AUTH-02: When ~/.claudebox/.credentials.json does not exist, claudebox starts without any error or warning (silent skip)

Network Isolation

  • NET-01: Block LAN/Tailscale access (RFC1918 + 100.64.0.0/10) while allowing internet egress
  • NET-02: Network namespace with controlled outbound via slirp4netns or veth pair

Enhanced Security

  • SEC-01: Env var leak detection — regex scan for patterns like *KEY*, *TOKEN*, *SECRET*
  • SEC-02: PID namespace isolation (--unshare-pid)
  • SEC-03: Git credential isolation — sandbox-specific .gitconfig with HTTPS-only credential helpers

Extensibility

  • EXT-01: Project-local tool declarations via .claudebox.toml or .claudebox/tools.txt
  • EXT-02: Additional mount paths via --mount-ro / --mount-rw flags
  • EXT-03: Configurable security profiles (different postures for different projects)

Out of Scope

Feature Reason
GUI/X11/Wayland passthrough CLI tool, no desktop integration needed
Audio/PulseAudio/PipeWire No audio needed for coding agent
DBus access Common sandbox escape vector, not needed
Seccomp syscall filtering Threat model is data exfiltration, not privilege escalation
Docker/OCI wrapping Nix+bwrap is lighter and daemonless
NixOS module (services/programs) Wrapper script derivation is sufficient
Multi-user / shareability Personal tool for endurance

Traceability

Requirement Phase Status
SAND-01 Phase 1 Complete
SAND-02 Phase 1 Complete
SAND-03 Phase 1 Complete
SAND-04 Phase 1 Complete
SAND-05 Phase 1 Complete
SAND-06 Phase 1 Complete
SAND-07 Phase 1 Complete
SAND-08 Phase 1 Complete
SAND-09 Phase 1 Complete
SAND-10 Phase 1 Complete
SAND-11 Phase 1 Complete
SAND-12 Phase 1 Complete
SAND-13 Phase 1 Complete
SAND-14 Phase 1 Complete
SAND-15 Phase 1 Complete
TOOL-01 Phase 1 Complete
TOOL-02 Phase 1 Complete
TOOL-03 Phase 1 Complete
UX-01 Phase 2 Pending
UX-02 Phase 2 Pending
UX-03 Phase 2 Pending
UX-04 Phase 2 Pending
UX-05 Phase 2 Pending
UX-06 Phase 1 Complete
AWARE-01 Phase 3 Pending
AWARE-02 Phase 3 Pending
GIT-01 Phase 1 Complete
GIT-02 Phase 1 Complete
NIX-01 Phase 1 Complete
NIX-02 Phase 1 Complete
NIX-03 Phase 1 Complete
AUTH-01 Phase 4 Complete
AUTH-02 Phase 4 Complete

Coverage:

  • v1 requirements: 31 total, v2 requirements (partial): 2
  • Mapped to phases: 33
  • Unmapped: 0

Requirements defined: 2026-04-09 Last updated: 2026-04-09 after roadmap creation