Christopher Mühl 648f89459f docs: update README for phase 05 architecture

- Remove ANTHROPIC_API_KEY from requirements (OAuth auth works without it)
- Add --gc flag to flags table
- Rewrite "How it works" to reflect direct ~/.claude bind + per-project overlay architecture
- Drop stale symlink/CLAUDE.md references

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-16 10:06:52 +00:00

2.8 KiB

Raw Blame History

claudebox

Run Claude Code inside a bubblewrap sandbox with an allowlisted environment, explicit filesystem mounts, and a minimal PATH.

SSH keys, GPG/age secrets, cloud tokens, and Tailscale state stay completely invisible to the AI agent. If a secret is accessible inside the sandbox, it's a bug.

Quick start

nix run git+https://git.toph.so/toph/claudebox

Or add to your flake:

{
  inputs.claudebox.url = "git+https://git.toph.so/toph/claudebox";
}

Then add inputs.claudebox.packages.${system}.default to your environment.systemPackages or home-manager packages.

What it does

Starts Claude Code inside a bwrap namespace with --clearenv
Only allowlisted env vars enter the sandbox (HOME, PATH, TERM, EDITOR, LANG, ANTHROPIC_API_KEY if set)
Mounts CWD read-write, Nix store read-only, everything else is tmpfs
Provides nix shell and comma (, <tool>) so Claude can install tools on demand
Injects a SANDBOX.md so Claude knows it's sandboxed and how to get tools
Pre-configures git identity and safe.directory from host

Flags

Flag	Description
`--yes`, `-y`	Skip the env audit and launch immediately
`--dry-run`	Print the bwrap command without executing
`--check`	Verify prerequisites and exit
`--shell`	Drop into a bash shell instead of Claude Code
`--gc`	Remove stale per-project instance dirs and exit
`--`	Pass remaining args to Claude Code

Extra env vars

Pass additional host variables into the sandbox:

CLAUDEBOX_EXTRA_ENV=MY_VAR,OTHER_VAR claudebox

How it works

~/.claudebox/          # persistent config dir (host)
├── SANDBOX.md         # managed by claudebox, overwritten each launch
├── history.jsonl      # conversation history
├── .credentials.json  # Claude Code credentials (if present)
└── projects/
    └── <16-char-hex>/ # per-project instance dir (keyed by canonical git root)
        └── project-root  # records the canonical path for this instance

Inside the sandbox:
  ~/.claude            →  bind-mounted from host (plugins, skills, hooks, MCP all visible)
  ~/.claude/projects   →  bind-mounted from ~/.claudebox/projects/<hash>/ (per-project isolation)
  ~/.claude/history.jsonl → bind-mounted from ~/.claudebox/history.jsonl
  ~/.claude/SANDBOX.md →  bind-mounted from ~/.claudebox/SANDBOX.md

Each project gets an isolated ~/.claude/projects/ directory inside the sandbox, so conversation history and project state are separated per repo. Git worktrees share the same instance dir as their main worktree.

Requirements

NixOS or Nix with flakes enabled
User namespaces (enabled by default on NixOS)

License

MIT

2.8 KiB Raw Blame History