claudebox/README.md

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 github:toph/claudebox

Or add to your flake:

{
  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 (, <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:

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