docs: fix remote URL and add flake usage to README

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

2026-04-09 22:04:41 +02:00

2.4 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)
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

2.4 KiB Raw Blame History