70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# claudebox
|
|
|
|
Run [Claude Code](https://docs.anthropic.com/en/docs/claude-code) inside a [bubblewrap](https://github.com/containers/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
|
|
|
|
```bash
|
|
nix run github:toph/claudebox
|
|
```
|
|
|
|
Or add to your flake:
|
|
|
|
```nix
|
|
{
|
|
inputs.claudebox.url = "github:toph/claudebox";
|
|
}
|
|
```
|
|
|
|
## 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)
|
|
- 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
|
|
- 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 |
|
|
| `--` | Pass remaining args to Claude Code |
|
|
|
|
## Extra env vars
|
|
|
|
Pass additional host variables into the sandbox:
|
|
|
|
```bash
|
|
CLAUDEBOX_EXTRA_ENV=MY_VAR,OTHER_VAR claudebox
|
|
```
|
|
|
|
## How it works
|
|
|
|
```
|
|
~/.claudebox/ # persistent config dir (host)
|
|
├── CLAUDE.md # user-owned, claudebox ensures @SANDBOX.md import
|
|
└── SANDBOX.md # managed by claudebox, overwritten each launch
|
|
|
|
Inside the sandbox:
|
|
~/.claudebox → bind-mounted from host
|
|
~/.claude → symlink to ~/.claudebox
|
|
```
|
|
|
|
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.
|
|
|
|
## Requirements
|
|
|
|
- NixOS or Nix with flakes enabled
|
|
- User namespaces (enabled by default on NixOS)
|
|
- `ANTHROPIC_API_KEY` set in your environment
|
|
|
|
## License
|
|
|
|
MIT
|