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

docs: update README for phase 05 architecture

Browse source 
- 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>
This commit is contained in:
Christopher Mühl 2026-04-16 10:06:52 +00:00
parent dc3674c2fc
commit 648f89459f
1 changed files with 13 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -23,7 +23,7 @@ Then add `inputs.claudebox.packages.${system}.default` to your `environment.syst
## 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)
- 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](https://github.com/nix-community/comma) (`, <tool>`) so Claude can install tools on demand
- Injects a SANDBOX.md so Claude knows it's sandboxed and how to get tools
@ -37,6 +37,7 @@ Then add `inputs.claudebox.packages.${system}.default` to your `environment.syst
| `--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
@ -51,21 +52,26 @@ CLAUDEBOX_EXTRA_ENV=MY_VAR,OTHER_VAR claudebox
```
~/.claudebox/ # persistent config dir (host)
├── CLAUDE.md # user-owned, claudebox ensures @SANDBOX.md import
└── SANDBOX.md # managed by claudebox, overwritten each launch
├── 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:
~/.claudebox → bind-mounted from host
~/.claude → symlink to ~/.claudebox
~/.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
```
Claude Code reads `~/.claude/CLAUDE.md` which imports `@SANDBOX.md` via Claude's `@`-import syntax. Both `~/.claude` and `~/.claudebox` resolve to the same directory inside the sandbox, so hook paths and settings work without fixups.
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)
- `ANTHROPIC_API_KEY` set in your environment
## License