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 pulling 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-…) — what a registered runner connects with. Created at first connect and renewed automatically; you never type it.
• — Pack and provider credentials — your own secrets that pack actions use: a Nomad token, 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. It is not what keeps existing runners connected — 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 — no host access or enrollment key needed — and the outgoing token remains valid for 24 hours after the swap, so a runner that dies before saving the successor can still reconnect.

A token that expires anyway — a long offline stretch, 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 otherwise give the host a fresh key.

There is no separate token control. Disable or delete the runner identity in Runners:

• — Disable is reversible. Use disable to take a runner out of service: the identity and token remain stored, the connection is refused 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 — delete the runner and enroll the host again under a fresh enrollment key instead.

Pack and provider credentials#

A pack's credential — a Nomad token, a database password, 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 — your secret manager, 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.