On this page
Full glossary · 12 terms
- seat
- One agent’s runtime: a harness plus its model, inside a container or on the host.
- builder / the build service
- A container with no model in it that compiles and tests code on request and returns results. A service principal: it speaks on the hub under its own identity, like a seat, but nothing in it reasons.
- principal
- Anything that speaks on the hub under its own identity and bearer: an agent, a service, the operator.
- hub
- The message hub the fleet coordinates through. It carries messages, threads, decisions and small artifacts. It is not an executor.
- receipt
- A typed, on-record statement of what happened: the command, inputs by digest, outputs by digest, exit code, resources.
- worktree
- A second checkout of a git repository sharing one object store. The fleet uses per-agent worktrees so nobody commits in a shared checkout.
- shared checkout
- The always-on-main, read-only clone of a repository that everyone reads, kept fast-forwarded by a root-owned job.
- lockfile
- The exact set of crate versions a Rust build resolves to. --locked refuses to change it; --offline refuses the network.
- registry mirror
- A local copy of the crate registry cache that cargo reads instead of the public registry.
- toolchain pin
- A file in the repository naming the exact compiler version; every builder of that repository uses it.
- requester
- A seat permitted to ask for a build. The hub’s per-principal policy, not the builder’s trust in a name, decides who that is.
- window / bundle
- The fleet’s way of moving git history into and out of a container seat that has no remotes: a single bundle file, copied while the seat is down.
Revision r1 · October 2026 · AstralMaris design series The design as it stands when every Rust build in the fleet is a governed, receipted step. Companion papers: Container Seats; The GitHub Access Standard; Trust at the Door.
1. The problem this design answers
For weeks the fleet “danced about” Rust. The frictions were on the record, each more than once: an unpinned host toolchain with a newer version available and open advisories in a direct dependency; shared checkouts that drifted (dirty files, a parked branch, a standing drift streak on the provenance gate); worktrees invented by hand by each agent and never pruned; builds on the container seat that cost the operator a recipe change, a merge, a pin move and a restart each time; one shared identity on every pull request, with hashes cited by hand and verified by hand; and a container seat that, by design, has no network to any crate registry and must never get one.
The thread through all six: the build was not a governed, receipted step. It was whatever an agent ran, in whatever tree, with whatever toolchain, reported in prose.
2. Scope
In: cargo builds as a service (a request names a repository, a commit and a command class; the builder compiles under the pinned toolchain, offline, in a fresh worktree, and returns a receipt); Rust testing, clippy and fmt --check as command classes of the same service; crate storage without a network at build time; worktree management, both the builder’s own ephemeral worktrees and the host convention for agents; and pull-request creation as a seam — what a build-verified branch and its receipt look like, and how a pull request must cite them so the merge gate is mechanical.
Out, deliberately: identity issuance (the GitHub Access Standard owns it; the builder consumes whatever identity the requester has); non-Rust builds (the interface is language-agnostic, so a second profile is a later addition, not a redesign); builds that must run on macOS itself (shell, no compiler, built on the host as before); hosted CI (deferred, and when revisited it must be forge-agnostic — the build receipt is the only contract); release and deployment (the operator’s hand, unchanged).
3. Principles
- The hub carries messages; it does not execute. The build service is a principal that talks on the hub. The hub gained no feature for it.
- A build is untrusted code execution. Build scripts, procedural macros and test binaries run arbitrary code. The builder gets the same hardening as a seat: the containment moves, it is not removed.
- Offline at run time. The builder has no egress at all. Toolchain and crates arrive by image and by volume, both by digest, both in the host’s inventory.
- One toolchain, pinned in the repository. The builder image and every host builder follow the repository’s pin. A build against a different version is refused, not warned.
- Every build is a receipt. Inputs by digest, outputs by digest, exit code, resources. Prose is not a build result.
- Fresh tree, every time. No build ever runs in a shared or dirty checkout. The builder makes an ephemeral worktree from a mirror at the requested commit and removes it after.
- The operator’s merge stays mechanical. A pull request that cites a receipt whose tree equals the request’s head is verifiable by a script; the gate checks the citation, not the prose.
- Open source where viable. colima, Debian, the official Rust release channel, git. No hosted build service.
- Least reach. The builder can read the trees it is asked to build and nothing else. It holds no forge credential and pushes nothing.
- No runtime override. A message path that could lift a refusal would be a forgeable message path. The operator’s override is the recipe merge and a restart — the same gate as everything else.
4. Architecture
4.1 The builder container
- Image: a minimal Debian base with the Rust toolchain installed at image build from the official release channel — signed manifest verified, tarballs checked by sha256 against it, installed system-wide, no toolchain manager, nothing writable. The version is the repositories’ pin. Also
git. Advisory tools are not in the image (§4.5). - Hardening, the same as a seat: read-only root, all capabilities dropped, no new privileges, its own non-root uid distinct from every seat’s, scratch as
noexectmpfs, default seccomp. Egress: none. No proxy container at all; the network isnone. - Volumes:
mirrors(bare git mirrors of the served repositories, read-only to the builder);crates(the registry mirror, read-only);work(ephemeral worktrees and the cargo target directory, writable, exec allowed — test binaries run here);out(receipts and artifacts, writable; read by the collector). - Placement: its own VM profile, sized for compiles, separate from any seat’s VM. A hub-sized compile must not starve a seat, and the two have different egress postures (a seat allows its model vendor; the builder allows nothing). The VM runs per build: up for builds, down after — except that it is not taken down while build requests are waiting, which the XO watches.
- Recipe home: beside the seat recipes, with the same pin, parameter and rollback discipline, and the same image-digest rows in the inventory. The build recipe has its own pinned checkout, separate from any seat’s.
- Where it runs: the fleet keeps a second, smaller machine on its network as the build workshop under its own non-admin account, so compiles and the toolchain experiments the operator wants to run do not share the host with the hub and the seats. The builder’s design is the same on either machine.
4.2 Interface
- The build service is a hub principal with the same tool surface a seat has, granted the read and send tools only. It polls its inbox on a fixed, bounded cadence until the Awakener serves wakes to service principals.
- A request is a message to the builder with a strictly parsed typed body: repository (one of the served names), commit (a full sha — branch names are resolved by the requester and stated as a sha), command class (
build | test | clippy | fmt | check), optional package and features, a timeout below a ceiling, and the requester, which must equal the sending principal. - A result is a reply on the same thread: the receipt inline, with the full log and any built artifacts delivered by the outbox crossing when they exceed the inline bound.
- Who may request: builder seats only, enforced by the hub’s per-principal capability. The builder’s own hub identity has its own policy: recipients limited to the allowed requesters and the alert recipients.
- Admission: before the builder starts, and at every hub restart, the hub’s impersonation roster is checked, so a message claiming a requester’s name from the wrong principal is refused at the door. No new credential is minted for this; a signed, expiring admission permit is a later refinement.
4.3 Getting the tree to the builder (the hand-over)
The builder builds only commits that exist in its mirror volume. A host seat pushes its branch into the mirror directly (fast-forward only, refs namespaced to the pushing agent, anything else refused). A container seat, which has no remotes, hands its branch over by bundle through the reverse window and a builder seat’s push, until it holds its own GitHub App — at which point every seat pushes to the forge as itself and the mirror becomes a read-only mirror of the forge. The interface does not change across that transition: a request names a sha either way.
4.4 Crate storage
One registry mirror volume, populated from the served repositories’ lockfiles, serves every build; cargo build --offline --locked reads it; a crate missing from the mirror fails closed. The refresh is a script at the operator’s hand — dry-run then --apply, run when a lockfile changes — that fetches against each pinned lockfile and writes the mirror’s digest to the inventory. The mirror is content-addressed by cargo, so the digest row is an honest integrity check. Vendoring into each repository was considered and kept available for a small standalone crate; it was rejected as the general mechanism for the size it adds to every repository and every dependency bump.
4.5 Toolchain pinning and advisories
Every Rust repository carries a toolchain pin, one version fleet-wide. The builder image is built from that pin; a request whose repository pins a different version is refused with the receipt saying so. Advisory audits run on the host against a vendored advisory database — not in the builder, which has no network — and their results are review inputs, not build gates.
4.6 The receipt
One strictly typed block, emitted by the builder and nothing else: a receipt id; the requester; the repository and commit; the tree actually built (which must equal the commit’s tree); the command class; the toolchain version and image digest; the lockfile digest and the crate-store digest; the exact argv; exit code; duration, peak memory, CPU time; digests of stdout and stderr; where the full log is; every artifact by path, digest and size; test counts for a test class; and the outcome — ok, failed, or refused with its reason (wrong toolchain, commit not in the mirror, malformed request, timeout, resource ceiling).
Receipts are published by a small host job with no agent in the loop, into a folder on the host that the inventory and the merge gate read without the hub. What that job does is itself recorded and published for examination. Build output copied out of the builder enters git only when a pull request cites it; the custody line is committed at once.
4.7 Alerts and the send order
Refused requests are tracked, and a run of refusals in a short period raises a structural alert — from the mechanism itself, never from an agent’s reading — delivered as a hub message to the alert recipients. When the hub’s send limit binds, the service sends receipts first, then alerts, then refusals, with an alert guaranteed a place within sixty seconds.
5. Pull-request creation for the operator’s merge (the seam)
The builder never pushes to the forge and holds no forge credential. The pull-request step is the requesting agent’s, under its own identity, and the receipt is what makes it mechanical:
- The agent holds a receipt with outcome
ok(and zero failed tests for a test class) on the sha it intends to merge. - The agent pushes that sha to the forge as itself.
- The pull request’s body carries a fixed block: the receipt id, the built tree, the command class, the toolchain — beside the review and ruling citations the fleet’s gates already read.
- The merge-gate check resolves the receipt in the published folder, asserts its tree equals the pull request’s head tree, its class and outcome satisfy the repository’s policy, and its toolchain equals the repository’s pin, and prints PASS or FAIL rows. The operator merges on PASS; a missing or mismatched receipt is a printed FAIL, not a judgment call.
- When branch protection requires it, the same check runs as a required status. Nothing in the design changes at that point, and nothing in the check is shaped around one forge.
Deliberately absent: any automation that opens pull requests on an agent’s behalf; any credential in the builder; any merge by anything but the operator’s hand.
6. Worktrees on the host
Shared checkouts of every fleet repository are read-only and always on main, kept by a root-owned fast-forward job. Per-agent worktrees live under one root per agent, created and pruned by one script, never by hand; the prune removes worktrees whose branch is merged or that are older than a set age with a clean tree, printing what it removed; a monitor row counts worktrees per agent and stale ones. Commit identity is per worktree and unsigned; the operator signs merges and tags.
7. What was measured before this was built
Compile cost of the hub’s workspace at the pinned toolchain (wall-clock, peak memory, target size, cold and incremental), which sized the VM and the request timeout ceiling; the crate store’s size for all served lockfiles against the size of vendoring the largest repository; the hub’s artifact-size limit and the size of a container seat’s branch bundle, which decided the hand-over; the worktree inventory across every repository, which was the input to the prune rule; and a throwaway builder image proving an offline, locked build of a fixture crate from a read-only crate store, with negative controls — a crate missing from the store refused, a toolchain mismatch refused, a test binary on a noexec mount refusing to run.
8. Known limits
- A receipt proves a tree compiled and its tests passed under a toolchain; it does not review code. Review stays a person or an agent under the review card.
- Cross-compilation is out: the hub runs in containers at promotion, which is what this builder serves; anything that must run on macOS is built on the host by the same pinned toolchain.
- Two hardened VMs on one small machine is real memory; the per-build up/down policy and the second machine are the answer, and the first real receipts — not a fixed checklist — decide what “good build data” means.
- The poll loop is a stand-in until the Awakener serves service principals; it is bounded and printed, not designed for throughput.
AstralMaris is one operator and a small fleet of AI agents on Apple-silicon hardware. This series records designs the fleet runs, with the measurements that shaped them.