Install

Three binaries. emetc compiles Emet on your laptop; golemctl ships the result; golemd runs on each node.

What you need

• A Rust toolchain (the repo pins it via devenv / direnv; see apps/emet/CLAUDE.md).
• A Debian box (or container) for the agent when you want real host effects. The default fake reconciler needs no box.

1 — Build the binaries

git clone https://github.com/dull-ca/golem
cd golem
direnv allow            # or: devenv shell
cargo build --release -p emet -p golemctl -p golemd

That produces:

• emetc — the Emet compiler (crate emet).
• golemctl — the operator CLI.
• golemd — the per-host agent.

The devenv shell prepends target/release to PATH, so all three are callable by name from inside it — the rest of this page assumes you are.

emetc on PATH

golemctl apply shells out to emetc when you hand it a .emet file, so emetc must be on PATH. Outside the devenv shell, use cargo run -p emet -- build … and cargo run -p golemctl -- … directly.

2 — Run the agent

golemd needs a --host name — that is how it selects its scroll from a fleet manifest. For a first run, use the default fake reconciler, which records what it would do without touching the box:

golemd --host web --reconciler fake --listen 127.0.0.1:7474

1. Confirm it is up:

   curl -s http://127.0.0.1:7474/status
   # → {"host":"web","latest_revision":1}

   Revision 1 is the Init revision golemd writes when it opens its journal. Nothing has been applied yet.

2. When you want real effects on a Debian box, switch the reconciler — and give it a token file in the same breath:

   sudo install -d -m 0700 /etc/golem
   head -c 32 /dev/urandom | base64 | sudo tee /etc/golem/token > /dev/null
   sudo chmod 0600 /etc/golem/token
   
   golemd --host web --reconciler host --listen 127.0.0.1:7474 \
     --auth-token-file /etc/golem/token

   --reconciler host enacts real apt, systemd, and filesystem changes as root, so its port is root-equivalent control of the box. Started without --auth-token-file (and without [auth] token_file), golemd answers anyone who reaches that port. Loopback is the default bind and the deployed posture; operators reach it through an SSH forward golemctl opens for them. See Trust model.

The agent keeps its journal in --state-dir (default /var/lib/golem, file planroom.db). See the CLI reference for every flag.

The ungated form is for `fake` only

A tokenless golemd is the local-development posture and nothing else. Keep it paired with --reconciler fake, which records what it would do and touches nothing. Anything enacting real host state gets a token file, including the VMs on your own workstation.

What’s next

Write your first Emet program and watch it compile to glyphs.

The config