Node self-update
import { Callout } from ‘@astrojs/starlight/components’;
Nodes can update themselves: download a signed binary, verify it against a build-pinned ed25519 trust root, swap atomically, and re-exec — all without a reinstall. Identity, assignments, and on-disk state survive the swap, and the node resyncs on reconnect.
How verification works
Section titled “How verification works”- The build-pinned public key is the trust root. If no key is pinned (the default for downloaded release binaries), self-update is disabled — a fail-safe.
- Releases carry an ed25519 signature over a canonical
ReleaseManifest{version, goos, goarch, sha256}. - The node downloads the artifact, checks its SHA-256, and verifies the signature. An unverifiable artifact is never installed — fail-closed.
- Updates apply with jitter so the fleet rolls gradually rather than all at once.
Downloaded binaries: self-update is off by default
Section titled “Downloaded binaries: self-update is off by default”Pre-built release binaries ship without a pinned signing key, so self-update is
disabled out of the box. This is intentional — a node should only ever trust artifacts
signed by a key you control. To update nodes running the public binaries, re-run the
installer with --component node (it replaces the binary in place) and restart the
service.
Operators who want automatic fleet updates
Section titled “Operators who want automatic fleet updates”Self-update is for operators running their own signed node builds: you generate an
ed25519 signing keypair, pin the public key into your node builds, sign each release
with the private key, and stage it on the server via the StageRelease API. The server
then fans an UpdateNotice out to matching-platform nodes, which download, verify,
swap, and re-exec. Each deployment trusts only its own signatures.