toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code with --dangerously-skip-permissions, minus the danger
78 commits 1 branch 1 tag 574 KiB
Find a file
Christopher Mühl 6eb3b464f5 feat(05-01): register INST-01 through INST-04 requirements 
- Add Instance Isolation section after Authentication Passthrough
- INST-01: per-project isolated conversation history (no cross-contamination)
- INST-02: git worktrees share instance state via --git-common-dir
- INST-03: concurrent sessions safe (Claude Code manages own concurrency, D-13)
- INST-04: --gc removes stale instance dirs for missing project roots
- Add traceability rows mapping INST-01..04 to Phase 5
- Update coverage count from 2 to 6 v2 requirements
2026-04-13 09:01:22 +00:00
.planning feat(05-01): register INST-01 through INST-04 requirements 2026-04-13 09:01:22 +00:00
CLAUDE.md docs: create roadmap (3 phases) 2026-04-09 10:32:35 +02:00
claudebox.sh feat(05-01): rewrite mount architecture with per-project instance isolation 2026-04-13 09:00:53 +00:00
flake.lock fix: SHELL path, PATH isolation, --shell flag, nix-claude-code input 2026-04-09 14:59:43 +02:00
flake.nix fix: SHELL path, PATH isolation, --shell flag, nix-claude-code input 2026-04-09 14:59:43 +02:00
README.md docs: fix remote URL and add flake usage to README 2026-04-09 22:04:41 +02:00

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