Documentation

The durable explanation of each subsystem, rendered from the repository.

Subsystems

One document per subsystem. Each is the durable explanation — the feature specifications under specs/ hold the requirements that produced it.

Filesystem layoutWhere every file lives: the two config levels, the build context, and why a pre-011 layout is refused rather than migrated. OrchestrationHow a deployment becomes a compose project generated and run on the target host. Execution modesInteractive versus headless, workspaces, clone-on-start, and what the container's exit code means. Agent as codeThe .agent-container/ spec: plan, apply, destroy, and the deterministic identity that defines ownership. Agent interfaceThe machine-readable surface an AI agent drives: context, commands, and the installable skill. CredentialsThe least-exposure contract: never baked, never on argv, never printed, never on a volume. Egress controlPacket-level default-deny in a shared netns, the sidecar that holds NET_ADMIN, and why squid splices rather than bumps. Threat modelWhat this design defends against, what it does not, and the reconciliation every feature owes it. Shell integrationPrint/emit mode: config on stdout, humans on stderr, and the eval contract. ObservabilityTwo legs, one payload: an unconditional local trail plus a zero-dependency write-time export. Control planeA second image holding a standing key, so you can drive everything from a phone. InventoryWhat the tool created, verified by observation — and why unreachable is never reported as stopped. Doctor (preflight)Report whether a deploy would work without performing one. Smoke testThe manual end-to-end check for a fresh host.

Architecture decisions

ADR 0001 — Runtime and base imageAn architecture decision record: the context, the options and what was chosen. ADR 0002 — Host driver, provisioner and compose runAn architecture decision record: the context, the options and what was chosen.

The design contract

CLAUDE.md is the load-bearing contract: the invariants a change must not break. It is deliberately short. Everything longer lives in the documents above.

The reference guide is the repository README in full — deployment, the whole CLI surface, the image layering, the entrypoint and the release process.

Feature specifications

Every feature carries a numbered specification directory with its requirements, its checklists and its threat-model reconciliation. These stay on GitHub rather than being republished here.