>_ hermetarium
pihme / hermetarium

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.

CI · 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 version

Or download hermetarium-linux-amd64 from the releases.

Hello world

make test
make 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 version

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

Wall: runc container or Firecracker VMOperatorcurl · browserSupervisorhermetarium · os/execSquid (gate):18081 inbound · :3128 interceptInhabitantyour OCI image · listens :8080var/<id>/access.log→ io.jsonl via hermetarium logsVendor API (HTTPS)only if allowlisted in --aclcreateHTTP to urlstartsstartsreverse proxyegresswriteskey injected

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.

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