Skip to the content

Stand up Central Lite

Set up Central Lite on one Linux host: its org and keys, its HTTPS port, a first admin and a backup passkey, and its first encrypted backup.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Set up Central Lite, the self-hosted control plane for small fleets, on one Linux host: create its org and keys, sign its org root, start its one HTTPS port, register the console's first admin and a backup passkey, check every key's custody, and write its first encrypted backup. At the end it is ready to enrol machines.

1. Unpack Central Lite as its own account

Central Lite is one Linux binary, garm-central, with the fleet console built in. Install it from the tarball as Install Central Lite shows; no release carries the container image yet, because its base image is not pinned. Run every command as an unprivileged account, never root, that owns Central Lite's state directory, /var/lib/agentgarm-central. An unprivileged account cannot create a directory under /var/lib, so create it once as root, owned by that account; Central Lite refuses it unless it is 0700 and that account's.

The commands here run as that account with the tarball's bin directory on its PATH and the default state directory; with another, add --state-dir DIR to every command. Each admin action is chained in Central Lite's audit log with the operating-system account that ran it.

sudo install -d -o "$(id -un)" -m 0700 /var/lib/agentgarm-central

2. Create the org and its keys

garm-central init creates the single org: the online signing keys, the node certificate authority, the TLS key and the sealed tenant keys, and prints org with the org's id. --url is the origin nodes and browsers reach, with no path. Name a DNS host, not an IP address, since browsers refuse an IP address for passkeys; here the host is central.example on port 8443. The org is written once and never changed, and init refuses a directory that already holds one, so choose the URL before you enrol anything.

--keystore chooses where the keys live. The default, auto, takes the OS keystore where there is one (the macOS keychain, or the host's TPM 2.0 on Linux), else software: 0600 files under the state directory's keys. In a container it is always software, and whoever holds the state directory then holds Central Lite's keys. pkcs11: keeps every key wrapped under a key on a PKCS#11 token, with the token's PIN in a 0600 keys/pkcs11.pin file; kms: is refused as not built.

Every garm-central subcommand except serve prints its own output on stdout; stderr carries its notes and JSON log lines at warning level and above, among them, when keys are held without hardware custody, one warning that names them all (serve logs at info, with one custody warning per key), and AGENTGARM_LOG changes the level.

garm-central init --url https://central.example:8443

Checked by the walk: this command ran as written on a Central Lite host.

3. Sign the org root with Central Lite's own key

Nodes trust Central Lite through its org root metadata, which lists Central Lite's online keys and its TLS key, and Central Lite refuses every enrolment until one is installed. garm-central root lite signs it with a single org-root key in Central Lite's own keystore, a 1-of-1 root that nodes report as software custody whatever keystore holds the key. It prints org root metadata version 1 installed (custody software). The metadata lasts 365 days by default (--expires-days, at most 1095); run root lite again before then to sign the next version.

A 1-of-1 root on the same host as the online keys means whoever controls that host can sign a new root, for example one listing an approver of their own: remote approvals under it rate C, never B. An offline root of two or more keys is signed in a ceremony (root template, then root install); no production org root exists yet, because that ceremony has not been held. Moving a Lite org to a ceremony root later means enrolling the nodes again.

The same goes for fleet kill orders: nodes check each order's approver signatures against this root, so under a 1-of-1 root whoever controls the host can add an approver and issue an order alone, and every order's report says the custody is software. init created the org's evidence key, which signs Central Lite's evidence bundles of a task, and this root lists it; an org created before that key existed gets it the next time root lite runs.

garm-central root lite

Checked by the walk: this command ran as written on a Central Lite host, and the output showed org root metadata version 1 installed (custody software).

See also

Approve a CI job's risky step from your laptop

Mark the commands a CI job may wait on a person for, and approve the job's request from the console with your passkey, for exactly that call, once.

4. Start the HTTPS port

garm-central serve answers nodes and the console on one HTTPS port, prints garm-central listening on with the address, and runs until it is stopped, so keep it under your own service manager. It refuses to start without its keys. While it runs it sweeps records past their retention every hour and writes an encrypted backup every 24 hours, keeping the newest 7.

Nodes pin Central Lite's long-lived TLS key, not its certificate. Browsers refuse passkeys on a page with a certificate error, so give the console a certificate from a public CA for that same key: garm-central tls csr writes a request signed by the key, which never leaves the keystore; an ACME client such as certbot or lego issues the certificate from it; and garm-central tls install checks the chain and installs it for the next start of serve. Renewals certify the same key, so nothing the machines pin changes. Without one, serve mints a self-signed certificate at each start, which you would have to trust on your device after every restart.

garm-central serve --listen 0.0.0.0:8443

Checked by the walk: this command ran as written on a Central Lite host.

5. Register the first admin and a backup passkey

garm-central admin bootstrap prints a one-time code on stdout: it works once, for 15 minutes, only while no admin exists, and Central Lite keeps only its hash. Open Central Lite's URL in a browser: while Central Lite has no admin, the console opens on “Register the first admin” (if it shows Sign in instead, choose “First admin? Use a bootstrap code”). Enter the Bootstrap code and the Admin name (the one --name bound it to), and choose “Register a passkey”. Your authenticator asks twice: once to create the passkey and once to prove it holds it.

You are then signed in to the whole console. While you hold one passkey it asks for a backup: choose “Add a backup passkey” and save it somewhere other than the first (another password manager, a phone or a security key; the browser refuses the store that already holds your first), and confirm with your first passkey. “Not now” hides it until the page is next loaded. A session lasts at most 12 hours, ends after 30 minutes idle, and a restart of serve signs everyone out. Further admins are added on the host with garm-central admin add, come from your identity provider through SCIM (Provision and remove people with SCIM), or, once you turn on garm-central sso jit on, are created at their first SSO sign-in with the role their groups map to, never owner (Sign in to the console with your identity provider). Settings → Roles & access lists the admins; adding them in the console is not built.

You are an owner, the role that can do everything, and so is each admin added with admin add: give one a narrower role and remove its owner binding (Give people the right access in the console). Admins can also sign in through Okta, Entra ID or another OIDC provider, beside their passkeys, and every change still asks for a passkey (Sign in to the console with your identity provider).

garm-central admin bootstrap --name alice
garm-central admin list

Checked by the walk: these commands ran as written on a Central Lite host.

The console's first-admin form, with the bootstrap code, the admin's name and the passkey button

6. Recover an admin who lost their passkey

If an admin loses every passkey, recovery starts on Central Lite's host, as the account that runs it: garm-central admin recover --name alice prints a one-time recovery code for that admin. It works once, for 15 minutes, and a newer code replaces it. In the console, choose “Lost your passkey? Use a recovery code”, enter the Recovery code and the Admin name, and choose “Register a new passkey”: the new passkey is added and the admin is signed in with it. Every admin is alerted, and both the code and the new passkey are chained in Central Lite's audit log.

Without a browser on hand, the same host account can register a FIDO2 security key with libfido2's tools. garm-central admin fido2-input prints what the key signs to create a passkey for Central Lite's host name, then what it signs to prove it holds it, and admin passkey-add registers it once both verify with user presence and verification. Make it a discoverable credential (-r), since the console signs in without a credential list; DEVICE is the key's path, which fido2-token -L lists. Every admin is alerted, and the change is chained in Central Lite's audit log.

Access to that host account is the recovery path, so guard it as you guard the admins. Recovery codes are printed when needed, never ahead of time. A recovered admin's lost passkeys stay registered, since removing a passkey, or an admin by hand, is not built yet. Under SSO required, recovery codes work only for owners.

garm-central admin recover --name alice
garm-central admin fido2-input --name alice > cred.in
fido2-cred -M -r -v -i cred.in -o cred.out DEVICE
garm-central admin fido2-input --name alice --registration cred.out > assert.in
fido2-assert -G -p -v -i assert.in -o proof.out DEVICE
garm-central admin passkey-add --name alice --registration cred.out --proof proof.out

7. Check every key's custody

garm-central status shows the org, its URL and keystore, the org root (here 1-of-1, key_custody software and its expiry), the TLS key's hash and the node CA, then every key with its id and key_custody: org-root, policy, revocation, approval, audit-head, evidence, node-ca, tls and sealing. Below them come the nodes enrolled, the enrolment tokens, the audit chain's length, the retention in force per class and the newest backup, which reads none written until the next step. The last lines are the licence (none (community; no node limit) without one), the policy repository, the newest policy bundle and the open rollout, which on a new org read no repository configured, none published and none open.

garm-central status

Checked by the walk: this command ran as written on a Central Lite host, and the output showed none written.

See also

Enrol developer machines

Enrol a machine in Central Lite with a one-time token that pins Central Lite's key, see it report in the inventory, and let its users enrol presence keys.

8. Write the first backup

garm-central backup create works while serve runs. It writes a consistent copy of Central Lite's database, encrypted under a key of its own, to a new 0600 file under the state directory's backups, and prints its id, path, size and SHA-256. backup list shows every backup, newest first.

Each backup's key is sealed in Central Lite's keystore, never in the file, and the keystore is not in any backup: a restore needs this same keystore. Keep the keystore (the state directory's keys under software custody) backed up under its own custody, apart from the backups.

garm-central backup create
garm-central backup list

Checked by the walk: this command ran as written on a Central Lite host.

See also

Back up and restore Central Lite

Write Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next.