Runner credentials

The credentials a runner fleet runs on: the enrollment key that registers hosts, the token each runner holds, and the provider credentials packs read.

For every other emisar credential, and what revoking each one breaks, see Rotate and revoke credentials.

• — Enrollment key (emkey-enroll-…) registers a new runner. You mint it in the console: single-use for one host, reusable for a fleet template.
• — Per-runner token (rnrtok-…) is what a registered runner connects with. It is created at first connect and renewed automatically; you never type it.
• — Pack and provider credentials are your own secrets that pack actions use, such as a Nomad token or a database password. They live on the host and are never emisar credentials.

Each section below covers the rotation and revocation for one of these. Every rotation follows the same shape: create the new value, update whatever uses it, prove the new path with a real call, then revoke the old value and prove it now fails. The full seven-step version is in the rotation sequence.

Runner enrollment keys#

An enrollment key registers new runners. Existing runners do not depend on it: each host exchanged its key for its own token on first connect.

• — Rotating a reusable provisioning key. Mint a new key under Runners → Enrollment keys. Update the template that sets EMISAR_ENROLLMENT_KEY in cloud-init, Packer, or the autoscaling startup script. Boot one host to prove enrollment with the new key. Then revoke the old key.
• — Revocation blocks registrations, not connections. After revoking, a host presenting that key is refused at registration. Runners already enrolled under it keep running on their own tokens and are unaffected.
• — Re-enrolling a host you keep. A runner stamps its cached token with a fingerprint of the key that minted it. Set the new key in /etc/emisar/runner.env (or re-run the installer with the new EMISAR_ENROLLMENT_KEY, which writes it for you) and restart. The fingerprint no longer matches, so the runner registers again under its configured runner.id or its hostname and replaces the cached token. No second runner identity appears.

Manage the runner fleet covers key models, caps, and expiry; Autoscaling fleets covers the boot-time flow.

Per-runner tokens#

A runner token lasts 90 days and renews itself. On a connection at 60 days, the runner exchanges it for a successor without needing host access or an enrollment key. The outgoing token remains valid for up to 24 hours after the swap, or until its existing expiry if sooner. So a runner that dies before saving the successor can still reconnect.

A token that expires anyway, for example after a long offline stretch or repeated refresh failures, is refused. The runner then discards it and re-registers with its stored enrollment key; a spent single-use key works only for the original identity, so for a new identity, give the host a fresh key.

Open a runner in Runners to see its Connection key expiry and choose Rotate key. The runner saves the new key and reconnects automatically; running actions continue. An offline runner rotates when it reconnects. The request stays pending until the runner connects with the new key. Older runners need an update before they can accept this request. No key is shown or copied in the console.

Expiry refers to the key used for the runner's latest connection, not an unused replacement. If that connection hasn't identified its key yet, the console says expiry will be available after the next connection. A rotation request never extends an expired key.

To stop access, disable or delete the runner:

• — Disable is reversible. Use disable to take a runner out of service: the identity and token remain stored, emisar refuses the connection while the host service keeps retrying, and enabling it restores service without host access.
• — Delete cannot be undone. The token stops working, the next connection is refused, and the service exits rather than retrying forever. Run and audit history for that runner is preserved.
• — A suspected leak needs a new identity. Disabling and re-enabling hands the same token back, so delete the runner and enroll the host again under a fresh enrollment key instead.

Pack and provider credentials#

A pack's credential, such as a Nomad token, a database password, or a cloud key, is never an emisar credential. The runner reads it from its own environment. The control plane does not distribute or store it as configuration, and it cannot rotate the value. If an action prints the value and redaction misses it, the value can appear in run output.

1. Rotate the value in the system that owns it, such as your secret manager or the provider's console.
2. Update /etc/emisar/runner.env on each affected host, keeping it mode 0600.
3. Restart the service. The environment is read at process start, so a reload of the pack catalog is not enough.
4. Run one safe read-only action from that pack and confirm it succeeds.
5. Revoke the old value at the provider, then run the same action again to confirm nothing still depends on it.

Manage the runner fleet lists the variables a pack reads, and explains how the inherit_env allowlist decides what reaches an action.