Hermetarium
The world an agent wakes up in: an OCI image it may use freely as root, behind a wall with Squid as the only, logged way out.
· releases tagged
hermetarium/vX.Y.Z and porter/vX.Y.Z
#What it is
An agent that can run a shell and install packages should not run on the operator’s machine. Hermetarium is the world the agent wakes up in: an inhabitant boots inside an OCI image and may use its Linux freely (shell, package managers, rewriting files), as root. It is not a per-command sandbox and not a tool the agent calls.
The wall is outside the image. A Go supervisor boots the image behind either a weak (Docker/runc) or strong (Firecracker microVM) wall, starts Squid as the only network path with an operator-supplied ACL, and turns Squid’s access log into an I/O log. If that path cannot be applied, the habitat does not start (fail closed). API keys never live in the image; Squid injects them from the host-side ACL.
#Current status
Last updated 11 November 2026 · main@ac73da0
The full test suite passes on the main branch in continuous integration, which builds in a pinned Nix environment, on a machine with Docker and hardware virtualization. It shows the core promise on both walls, the lighter Docker container and the stronger Firecracker virtual machine with its own kernel: unallowed traffic is blocked, allowed traffic goes through the Squid proxy and into the log, and the operator can reach the program inside. A small example agent runs on both walls with its API key added by the proxy, never stored in the image. The ready-made images for Claude Code and Grok Build build, and their command-line tools run with no keys inside. From 1.0.1, Grok Build has been shown to work on the Firecracker microVM. The latest releases are porter/v0.2.2 and hermetarium/v1.0.2.
Chat with a real AI model is not part of the regular tests: the ready-made images reject the test stand-in for the vendor, and tests with real keys run only when started by hand. Claude Code has no successful run on the Firecracker wall. The strong wall needs an x86-64 host with hardware virtualization; its virtual machine gets one CPU, and memory and disk can be set when it is created. Release binaries exist for 64-bit x86 Linux only. The log records metadata about each connection, not its contents. Chat is one request and one reply at a time. Six issues are open, all planned work: a guided proxy setup, a check that every expected access is logged, running Fregoli and its tools inside a habitat, Git Warden as the Git proxy, an optional OpenCode image, and a sandcastle package.
#Key concepts
Supervisor
supervisor/: the only operator-facing command. Drives Docker, Firecracker and Squid as processes via os/exec, not their SDKs.
Two walls
--wall weak (default): Docker/runc, host kernel shared. --wall strong: Firecracker microVM with its own guest kernel; needs /dev/kvm and x86_64. Same image either way.
Squid, the logged path
A pulled Squid image runs as a sibling (not linked; GPLv2 stays in Squid). Default deny; allowlists and API-key header injection live in the --acl file.
I/O log
hermetarium logs <id> syncs Squid’s access.log into io.jsonl: time, direction, protocol, destination, port, method, allowed, bytes. Bodies are off.
Porter
porter/: tiny HTTP adapter inside inhabitant images. Listens on :8080; each POST is one CLI turn for claude or grok.
Inhabitants
inhabitants/: Dockerfile + squid.conf templates for Claude Code and Grok Build. Copy and adapt; the contract is root, TCP 8080, iproute2, vendor URL, dummy key. One possible inhabitant from outside the repo is Fregoli, whose own image serves HTTP on 8080 directly.
#Getting started
Needs Docker and Go 1.24+ on PATH. The strong wall also needs /dev/kvm and x86_64 (Firecracker is fetched on first use and runs in a privileged helper container; no host sudo).
From source
git clone https://github.com/pihme/hermetarium.git
cd hermetarium
make build
./bin/hermetarium versionOr download hermetarium-linux-amd64 from the releases.
Hello world
make testmake echo-image
make build
id=$(./bin/hermetarium create --wall weak --image hermetarium/echo:dev --acl examples/echo/squid.conf)
./bin/hermetarium url "$id"
curl -sS -d 'hello' "$(./bin/hermetarium url "$id")"
./bin/hermetarium logs "$id"
./bin/hermetarium destroy "$id"make echo-image needs Docker and tags hermetarium/echo:dev. --image is any local or pullable OCI image that listens on TCP 8080 (myorg/claude:dev below is a placeholder for an image you build); url is the host address that reaches it through Squid. --wall strong works the same; --mem MiB and --disk MiB set the microVM size (default 512 and 1024).
An official CLI as inhabitant
sed 's/__VENDOR_KEY__/sk-ant-.../' inhabitants/claude-code/squid.conf > /tmp/claude.acl
id=$(./bin/hermetarium create --wall weak --image myorg/claude:dev --acl /tmp/claude.acl)
curl -sS -d 'Run id -u' "$(./bin/hermetarium url "$id")"CLI
hermetarium create --wall weak|strong --image NAME --acl FILE
hermetarium url <id>
hermetarium exec <id> -- <cmd> # weak wall only, not the product path
hermetarium logs <id>
hermetarium destroy <id>
hermetarium versionTests: make test (mock vendor API, CI default) and make test-live (real vendor keys via HERMETARIUM_*_API_KEY, optional). Walls, Squid contract, logs and custom images: usage guide.
#Architecture & layout
The operator reaches the inhabitant only through Squid (hermetarium url prints a 127.0.0.1 port published from the gate). Box HTTP is intercepted to :3128; the --acl file is expected to deny by default and allowlists and key-injects vendor hosts. Squid’s access.log lives in the host instance directory.
| Path | Contents |
|---|---|
supervisor/ | Go supervisor; entry point supervisor/cmd/hermetarium |
firecracker-helper/ | TAP + Firecracker scripts for the strong wall (embedded in the binary) |
porter/ | HTTP → CLI-turn adapter copied into inhabitant images |
inhabitants/ | Claude Code and Grok Build templates (Dockerfile + squid.conf) |
examples/ | Test stand-ins: echo (HTTP echo) and agentd (tool loop against a mock API) |
tests/ | Integration tests (hello-world, agentd, official-CLI smoke), harness, vendor mock and probe |
docs/images/ | Diagrams used in the readme and on this site |
var/<id>/ | Instance state under the data root (HERMETARIUM_ROOT, the checkout, or ~/.local/share/hermetarium) |