Integrated Sandbox for AI Coding Agents

h5i (pronounced high-five) gives a coding agent full autonomy inside a throwaway box, and gives your machine nothing to lose. The code, the toolchain, the tests, the dev server and the agent itself run inside one boundary. Your host directories are not mounted into it, your credentials never enter it, and the only thing that comes out is a patch you reviewed, next to a receipt of everything that ran.

The pivot in progress. h5i began as a provenance system for AI coding work. It is being rebuilt around the boundary, which was always the part worth having. ROADMAP.md is the plan of record: what stays, what was cut, and what is still coming.

---

Install

curl -fsSL https://raw.githubusercontent.com/h5i-dev/h5i/main/install.sh | sh

Or build from source:

cargo install --path .

Linux and macOS. The two confine by different means: Linux uses Landlock, seccomp and namespaces, macOS uses Seatbelt. What that buys you is close but not identical, so run h5i box probe. It reports the mechanism your host actually has and what it can enforce, rather than a tier name that means different things in different places. Two optional runtimes add tiers on top of either: rootless Podman gives you container, and microsandbox (msb) gives you microvm on a host with hardware virtualization — /dev/kvm on Linux, Apple Silicon on macOS.

The gaps worth knowing before you pick a host: macOS has no per box memory or process-count cap (Darwin has no cgroups, does not enforce RLIMIT_AS against the mmap'd heap every modern runtime uses, and scopes RLIMIT_NPROC to the whole user rather than to one box), and no syscall filter. h5i box status marks a declared-but-unenforced limit with * rather than reporting it as enforced. Use the container or microvm tier if you need any of those: both cap memory and process count in the runtime itself.

Use it

h5i box                          # a box from this repository
h5i box --pr 1234                # a box from pull request #1234

Work in it. Every command is policy-enforced and recorded:

h5i box run <name> -- cargo test # one command; the exit code passes through
h5i box shell <name>             # an interactive confined session
h5i box status <name>            # the policy that was actually enforced
h5i box diff <name>              # what changed against the pinned base
h5i ui                           # the whole fleet on one screen, read-only

Get the work out through the gate, which is deliberately a human step:

h5i box export <name>
# → h5i-export/<name>/patch.diff    the change, path-validated
#   h5i-export/<name>/report.md     what ran, what was denied, what was redacted
#   h5i-export/<name>/receipt.json  the records, with the enforced policy digest

Nothing writes into your repository until you apply that patch.

What confinement means here

h5i box probe reports the tiers your host can run. h5i never silently downgrades: an unsatisfiable request fails closed.

Tier	What enforces it
workspace	a separate git worktree, no confinement
process	Landlock filesystem allowlist, seccomp deny-list, namespaces, rlimits
supervised	all of the above, plus a private network namespace with an nftables egress allowlist pinned to resolved IPs, DNS pinned by hosts file, and a seccomp-notify socket gate
container	rootless Podman, read-only rootfs, dropped capabilities, a portable image, and an HTTP/HTTPS proxy allowlist
microvm	a hardware-isolated guest with its own kernel, booted by microsandbox (msb) from the same OCI images, with the egress allowlist evaluated by the VM's network stack

Note the tradeoff: the container tier buys portability (any image, any Podman host), not stronger isolation. Its allowlist is proxy-based and binds only proxy-aware tooling. On Linux, supervised enforces egress at L3/L4 with nftables. On macOS, without netfilter, it uses a host-side proxy as the box’s only route out and therefore has the same limitation as container. h5i box capabilities reports whether egress_l3 is available.

microvm is the strongest tier and the only one that does not share the host kernel. It requires msb, hardware virtualization (/dev/kvm or Apple Silicon), and an image; otherwise, it is refused, never downgraded. Stronger isolation means weaker evidence: no per-request egress tally and no peak RSS.

No SSH keys, cloud credentials, or Docker socket enter a box. A runtime-scoped host proxy injects model API keys outside the boundary, preventing cross-runtime access. Each box receives a one-time copy of HOME state that is never written back.

For agents

The agent-facing interface is a skill, and the binary carries it:

h5i skill install                # writes it where your runtime looks
h5i skill show policy            # or just read a page
npx skills add h5i-dev/h5i       # if you do not have the binary yet

Documentation

• ROADMAP.md: where this is going, and what was cut to get there
• Official Website: project overview, Slides
• MANUAL.md / man h5i: full command reference
• CONTRIBUTING.md: we welcome contributions of any kind
• h5i man > ~/.local/share/man/man1/h5i.1: install the man page (generated from the CLI)

Parts of the documentation still describe the previous product. The roadmap says which, and the rewrite is tracked there.

What h5i does not claim

• It cannot stop an agent from putting your code in a prompt. Containment keeps the agent off your machine. Model egress is a separate control.
• The kernel is shared, below microvm. Podman and the kernel tiers are good against a runaway agent and careless dependency code, not against a targeted kernel exploit. isolation=microvm is the answer to that, and it needs a host with virtualization and an image — so it is opt-in, not the default you get by typing h5i box.
• The container tier's egress scoping is L7. Its allowlist is a proxy, so it binds proxy-respecting tooling only. supervised and microvm enforce at L3/L4 and do not have that hole.

License

Apache-2.0. See LICENSE.