Register a runner
A runner is a container that your operator runs on a host of your choosing, started from the execution-environment image you registered (itself derived from the released Helmhive runner image), so that its fingerprint matches the environment revision you pick here. Registration reserves its identity in the console and produces a reviewed handoff for your operator; it never edits or deploys infrastructure. The runner exchanges a one-time token for its own revocable credential the first time it starts.
Create the registration plan
Section titled “Create the registration plan”- Choose Register runner.
- Enter a Runner name and a Compose service name: the service name the runner will have in your operator’s Docker Compose deployment (lowercase letters, digits, and hyphens).
- Pick the Provider: Codex or Claude. Hermes is a third provider whose adapter (the runner-side integration for a provider) is not installed by default; ignore it unless your operator enabled it.
- Pick the Execution environment revision the deployed image will provide.
- Choose Create registration plan.
Every AI runner is registered with one job slot (it runs one job at a time) and the isolation
labels domain:code, runtime:isolated, and network:none, which cannot be removed.
Hand off the token
Section titled “Hand off the token”The Registration plan ready panel shows the One-time registration token, an Infrastructure handoff block (the Compose values and environment variables the runner needs, with the token as a placeholder), Provider authentication commands to run on the host, and a Verification block. Everything your operator needs is in that panel. The token expires after fifteen minutes and is never shown again once you dismiss the panel or leave the page. Copy it into your reviewed secret handoff, then choose I saved the handoff.
No provider credential is in the plan. Your operator deploys the runner with the token, then signs in to the provider from the trusted runner host.
If the token expires before the first exchange, choose Issue replacement token on the runner’s row. It invalidates every older unused token for that runner and shows a new one once.
What happens on first check-in
Section titled “What happens on first check-in”The runner exchanges the token for a credential. The exchange succeeds only if the deployed runner matches the plan: same provider, adapter, labels, concurrency, and execution-environment fingerprint. A mismatch is rejected rather than silently rewriting the plan. On success the runner moves from Awaiting deployment to Registered, becomes Active, and publishes its model catalogue and capabilities.
Confirm readiness
Section titled “Confirm readiness”The fleet row reports a readiness stage:
| Stage | Meaning |
|---|---|
| Registration plan ready | The plan exists but no runner has checked in yet. The row’s badge reads Awaiting deployment for the same state. |
| Provider login required | The runner is registered but its provider login is not authenticated on the host. |
| Ready for jobs | Authenticated, active, and advertising capacity. |
| Health check needs attention | The last health check failed; the row shows the failure. |
| Offline | The heartbeat is stale or missing. |
Expand a row to see the adapter version, current and last completed job, last heartbeat, authentication, model catalogue, execution environment fingerprint, labels, and capabilities.
Manage runners for draining, disabling, revoking, and login rotation, and Run diagnostics to prove the connection.