From 7430e9d64c728fc662446fd55f216f8bf037fd99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christopher=20M=C3=BChl?= <toki@toph.so>
Date: Thu, 9 Apr 2026 22:03:20 +0200
Subject: [PATCH] docs: add README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..68df053
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# 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