Golem

What it is

Golem is a pipeline with two ends and one contract between them.

• Emet — a typed, Elm-modeled configuration language. A program evaluates to a fleet: main : List Scroll, one Scroll per host. A scroll is a tree: each level holds either glyphs — a leaf unit — or named sub-scrolls, never both. There are exactly four glyph primitives — aptPackage, systemdService, file, lineInFile. Every field is a fully-evaluated concrete string; there is no templating layer.
• golemd — a per-host agent. It ingests the compiled manifest, selects its own host’s scroll, and reconciles the box toward it. Each glyph is enacted through a reversible reconciler: applying captures the prior host state so the edit can be undone exactly.

The contract between them is the manifest: emetc (the compiler) emits a binary, content-addressed artifact; golemd consumes it. Both ends compile against the same shared scroll-format crate, so they cannot drift.

Higher-level shapes — a container workload, a service with a firewall, an ingress — are not engine primitives. You build them in Emet and they lower to the four glyphs. The agent never grows a fifth resource kind.

Why it’s shaped this way

Abstractions live in the language

A “workload” or a “service” is an ordinary Emet function that returns a List Glyph. Read it, copy it, change it. The agent stays small because every abstraction compiles down to the same four primitives.

Statically typed authoring

Emet is Hindley-Milner typed with generics, records, case/if, and exhaustiveness checking. A missing field or a type mismatch is a compile error, before any bytes leave your laptop.

Content-addressed versioning

Every scroll is identified by a BLAKE3 hash of its deterministic bytes. Same bytes, same id, no-op. A changed field is a new id, and an upgrade. The manifest is versioned by format_version, not by hand-typed numbers.

Reversible reconcile

Applying a glyph captures what it changed. golemd only ever reverses edits it recorded — it will not remove a package, line, or file it did not add. That drives both upgrade (reverse old, apply new) and removal (reverse toward an empty scroll).

The pipeline in one line

Emet source ──emetc build──▶ binary manifest ──golemctl apply──▶ golemd
  ──diff by content id──▶ reversible reconcilers ──▶ the box ──▶ journalled revision

The diff is what keeps an unchanged apply free, and the journal is what makes the next one reversible.

See Architecture for each stage.

Start here

• Install the toolchain — build emetc, golemctl, and golemd.
• The config — write your first Emet program and watch it compile to glyphs.
• Applying changes — compile to a manifest and reconcile a box.

Guides

• A first glyph — the smallest fleet: one host, one package, one unit.
• A service abstraction — a thin helper on the shipped Quadlet library that lowers to a container quadlet, a unit, and a firewall fragment.
• A maintenance page — a parameterized Emet function built from file and lineInFile.
• A tour of the lichess fleet — the real multi-host lichess deploy: the shipped library, a fleet’s helpers on it, and the four glyphs it lowers to.

Tutorials

Hands-on walkthroughs against ephemeral Debian VMs — golemd’s real reconcilers, the way we ran them.

• Bring up the fleet — boot the VMs, deploy golemd, and prove that an ssh forward and a bearer token are the only way in.
• A failing unit — one broken leaf, eight siblings that settle anyway.
• A registry on the fleet — run a container registry on one VM; push to it from another.
• The website loop — golem building, storing, and serving golem’s own docs.

What is not built yet

Golem is honest about its edges. The following are roadmap, not working today:

• Per-user identity. The agent authorizes with one shared secret over an SSH tunnel, so it knows a caller was authorized, never which person submitted. SSO and an audit trail are designed, not built. Manifest signing is not on the roadmap at all. See Trust model.
• Server-side fleet coordination. golemctl fleet fans a verb out over an inventory, but the fan-out is entirely client-side: one connection per host, each golemd acting only on its own scroll. No coordinator, no ordered drain, no health-gated cross-host rollback.
• Any resource kind beyond the four glyphs. Everything else is an Emet abstraction that lowers to them.

See Status for the full breakdown.