Registration tokens

Registration tokens are short-lived secrets used only to create a runner. After configure / docker run / kubectl apply, the agent exchanges the token for a long-lived runner credential and discards it.

Token kinds

Prefix Kind Who mints it Where
axreg_ Customer / self-hosted Tenant admin on Setup Bound to a runner group
axpreg_ Provider / hosted fleet Platform provider on Hosted fleet Bound to a hosted group
axrun_ Runner auth (not a registration token) Issued at register Stored on the agent; used for heartbeat, lease, logs
!

Do not put axrun_ into a new install command. If the agent is gone, generate a new axreg_ / axpreg_ command and register again (or reuse the existing axrun_ only if the same config file is still on disk).

⚙

Setup fields

When you click Generate registration command:

Field Behavior
Max uses Blank = unlimited until expiry. Set 1 for a single host. Set ≥ replica count for Compose/Kubernetes scale-out. Range 1 – 10000.
Token TTL Minutes until the registration token expires. Range 1 – 43200 (30 days).
i

The generated panel shows token prefix, expiry, max uses, group, and labels.

⟳

Lifecycle

  1. Control plane mints the token and returns platform install instructions.
  2. You run the command on the host.
  3. POST /runner-agent/register validates expiry, remaining uses, revocation, and group.
  4. A runner row is created. Uses remaining decrement.
  5. Agent stores axrun_\* and starts heartbeats.
!

Revoke token on the generated command immediately stops further registrations. Existing online runners keep working.

▣

Cleanup on Setup

If the org has revoked or obsolete token rows, Setup shows:

▣
Clean revoked

Remove revoked records.

▣
Clean obsolete

Remove expired / unused historical records.

i

These cleanups do not break an install command you have already copied unless you revoke that token.

▣

Copy registration from an existing runner

Overview → ⋮ → Copy registration command mints a new token for the same group/platform placement so you can rebuild a host without re-entering Setup options.

+

Security

  • Treat axreg_\* / axpreg_\* like a one-time bootstrap secret.
  • Tokens are hashed at rest on the control plane.
  • Customer tokens cannot register into the provider fleet; provider tokens cannot register as tenant self-hosted runners.
  • Runner JWTs (axrun_\*) are hashed at rest. A 401 on heartbeat means re-run configure with a new registration token.

See Security.

›_

Environment variables (agent)

Variable Purpose
AXIO_API_URL / AXIO_SERVER_URL Control plane API including /api/v1
AXIO_REGISTRATION_TOKEN axreg_\* or axpreg_\* for first boot
AXIO_RUNNER_TOKEN Override long-lived bearer after register
AXIO_RUNNER_NAME Fixed name (one host only)
AXIO_RUNNER_NAME_PREFIX Unique names per replica
AXIO_RUNNER_LABELS Comma-separated labels