Add README with security model documentation

README.md

@@ -0,0 +1,26 @@
+# agent-sandbox
+
+Sandbox agentic coding assistants with [bubblewrap](https://github.com/containers/bubblewrap). Limits what an AI agent can see and modify on the host, reducing the blast radius of prompt injection and accidental damage.
+
+## Modes
+
+### Whitelist
+
+Tight sandbox for normal agent coding tasks. Only explicitly listed paths are visible — system binaries, libraries, a subset of `/etc`, `/sys` (all read-only), synthetic `/dev`, private `/proc`, `/tmp`, `/run`, and the working directory (read-write). Everything else is invisible.
+
+### Blacklist
+
+Looser sandbox for system-level debugging with agent assistance. The host filesystem is mounted read-only, with targeted overlays hiding sensitive paths (credentials, history, secrets, sockets, input devices). `/run` and `${XDG_RUNTIME_DIR}` are replaced with tmpfs mounts that only expose the paths needed for system tooling (`systemctl`, `resolvectl`, `journalctl`, etc.).
+
+The threat model is prompt injection and accidental damage, not a determined attacker with user-level access.
+
+**Not protected in blacklist mode:** arbitrary readable files outside the sensitive paths list, and D-Bus method calls (access control is daemon-side).
+
+## Escape hatches
+
+When the agent needs access to something the sandbox blocks, use `--rw` or `--ro`:
+
+```bash
+agent-sandbox --rw /var/run/docker.sock -- claude --dangerously-skip-permissions
+agent-sandbox --ro ~/.aws -- claude --dangerously-skip-permissions
+```