Guide 50 of 61 · Running a fleet with Central Lite
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.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Create a one-time enrolment token in Central Lite, hand it to a machine's agentgarmd, which pins Central Lite's key from the token before it sends anything, and see the machine report in Central Lite's inventory. Then keep its audit key trusted after a rotation, and let its users enrol their presence keys with a grant from Central Lite instead of root on the machine.
1. Create a one-time enrolment token
On the Central Lite host, garm-central token create mints a token (agt1.…) that carries everything a machine needs to find and trust Central Lite: the URL you gave init, the org, the org root's key fingerprints and the SHA-256 of Central Lite's TLS key. It works once and expires within 24 hours, the default (--expires-in, for example 4h). Central Lite refuses to create one until its org root metadata is installed and unexpired.
The token is shown once: on stdout, or with --out in a new 0600 file, never over an existing one; its id and expiry go to stderr. Central Lite keeps only the secret's hash, and creating it is chained in Central Lite's audit log. --profile names the token's profile (lower-case letters, digits, - and _; default managed; ci-oidc is reserved for CI runners).
--group names a host group the machine joins as it enrols, so a role bound to that group reaches it from its first report (host groups). The group must exist already (garm-central group create), or the token is refused. The machine joins it in the same step that spends the token, and the join is chained in the audit log. The token names the group by name, so Central Lite refuses garm-central group delete and group rename for that group until the token is used or expires. If the group is gone all the same when the token is used (say, after restoring an older backup), the machine still enrols, in no group, and Central Lite raises the alert enrolment_group_missing: add it with garm-central group add.
In the console, Enrolment does the same: set the Profile (prefilled managed) and choose how long it is Valid for (1, 4, 8 or 23 hours), then “Create with a passkey”, which asks your passkey again for this exact token. The token appears once, under “Copy this token now: it will not be shown again”, with “Copy the token”; the form waits until you hide it. The form names no host group yet: for a token whose machine joins a group, use --group on the Central Lite host.
garm-central token create --out enrol-tokengarm-central token create --group laptops --out laptop-tokenChecked by the walk: this command ran as written on a Central Lite host.
2. Enrol the machine with the token
Take the token to the machine and give it to sudo agentgarm node enrol on stdin. It is never an argument. --token-file reads it from a file instead, but only from a regular file owned by root with no group or other permissions (0600 or 0400), so a file another account wrote is refused. Enrolment is root only, on a root install, from outside every governed task.
The machine needs nothing else from you. Its agentgarmd connects to the URL in the token and checks Central Lite's TLS key against the hash in the token before it sends the token, so a server that is not your Central Lite never sees it, and Central Lite's self-signed certificate needs no trust on the machine. It then creates a fresh mTLS key, registers, verifies Central Lite's org root metadata against the token's fingerprints, and writes Central Lite's signing keys, one keyring per role.
It prints the org, the host id and its SPIFFE id, the certificate's expiry (90 days, renewed automatically at two thirds), the org root metadata version and its custody (software under Central Lite's root), and the org's fingerprint key, which replaces the machine's own. Uploads start at once. A refusal exits 2: an enrolled machine must node leave first, and a spent or expired token needs a new one.
sudo agentgarm node enrol < enrol-tokenChecked by the walk: this command ran as written on a Linux node enrolled in Central Lite.
3. Find the machine in Central Lite
garm-central node list shows every node with its host id, hostname, state (enrolled, revoked or left), last report and, per stream, what Central Lite acknowledged, the events it holds and any lost. A node reports as soon as its control channel opens, then every 5 minutes. garm-central node show with the host id adds the registration, each stream's detail, the audit keys Central Lite pinned for it, and its last report: components, policy, keys and their custody.
In the console, Inventory lists the same nodes under Nodes, with their OS, sentinels, agentgarmd version, policy, key custody, last report, state and host id.
The host id is what a kill order's host: scope names. A node whose agentgarmd is too old to apply an order is counted as too old in the order's blast radius, and never sent one.
It is also what puts a machine enrolled without a group in one later, so that a role bound to that group reaches it: garm-central group add with the group's name and the host id (host groups). A token made with --group did this at enrolment.
garm-central node listgarm-central node show HOSTgarm-central group add laptops --host HOSTChecked by the walk: this command ran as written on a Central Lite host.
See also
Stop agents across a fleetSuspend, terminate or lock down agents on one machine, one agent, one person or the whole fleet, with an order two approver keys sign and each node checks.
4. Accept a machine's new audit key
Central Lite believes a node's audit chain heads only under the audit key it pinned when the node registered. If the node later starts a new chain under a new key (a key rotation, or a recovered store), nothing cryptographic links the two keys, so Central Lite raises audit_key_rotated and ignores that node's heads until you accept the key or the node enrols again.
Read the key id on the machine itself, from the node key line of agentgarm status, and compare it with the alert; never copy it from the alert alone, which only repeats what the report claimed. Then accept it on the Central Lite host. Central Lite takes it only when the node's last report names that key and its head proves the rotation. There is no console action for this.
agentgarm statusgarm-central node accept-audit-key HOST --key-id IDChecked by the walk: this command ran as written on a Linux node enrolled in Central Lite.
5. Let each user enrol a presence key
Approving an ask needs the user's presence key, and on its own only root on the machine opens the window to enrol one. On an enrolled machine, Central Lite can issue a presence enrolment grant instead: garm-central presence grant names the node and the local account, lasts 15 minutes by default and at most an hour, and is shown once. In the console, Inventory's “Presence grant” on the node's row does the same after “Issue with a passkey”.
As that user, not root, run agentgarm enrol --grant-file - and paste the grant; the machine's agentgarmd checks it, uses it once, opens that user's 5-minute window, and the key enrolment follows as usual. The grant is signed by Central Lite's online approval key, so whoever controls Central Lite's host could open a window for a named user on a named machine. Revoking that key (garm-central approver revoke) stops every grant it signed, on each node that applies the revocation list. A node gets the list on its next delivery over the control channel, not at once; one that is offline gets it when it next connects.
garm-central presence grant --host HOST --user aliceagentgarm enrol --grant-file -See also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.
6. Remove a machine
sudo agentgarm node leave on the machine deregisters it: Central Lite revokes its certificate, and the machine removes the certificate and Central Lite's keys and stops uploading the events Central Lite never acknowledged, which stay in its local store with its audit chain. When Central Lite cannot be reached, the machine leaves locally and says so; revoke it in Central Lite too. garm-central node revoke stops a machine you no longer trust from the Central Lite host: every service refuses its certificates at once, and the next revocation list names them. In the console, Inventory's “Revoke” on the node's row does the same after a reason and “Revoke with a passkey”.
sudo agentgarm node leavegarm-central node revoke HOST --reason "laptop lost"See also
Stop an agent task on any machineKill or suspend one agent task from the Central Lite host, check that the node applied it, and revoke a machine you no longer trust.