opschain admin runner-token create
Included from Basic tier
opschain admin runner-token create [--server <url>] [--group <name>]
[--labels a,b] [--ttl <d>] [--ephemeral] [--max-uses <n>]
Mints a runner registration token: the credential a new runner redeems to enrol into the fleet. The token carries its enrolment policy — the group the runner joins (inheriting that group's placement contract), the labels stamped onto it, a lifetime, an optional redemption cap and the ephemeral flag — so the runner side needs nothing but the token.
The token value is shown exactly once, here. The server stores only a
fingerprint; opschain admin runner-token list names tokens by that
fingerprint and can never recover the value. Capture it from stdout and
deliver it to the runner host.
The server and credential resolve the way every admin verb (and admin login's help) documents them: --server, then OPSCHAIN_SERVER / the
active context; --auth-token, then $OPSCHAIN_ADMIN_TOKEN, then the
token stored by opschain admin login.
Flags
| Flag | Meaning |
|---|---|
--server <url> | Server base URL (default: the active context / OPSCHAIN_SERVER). |
--auth-token <token> | Admin bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login. |
--group <name> | Runner group the token enrols into (default default). Minting for a new group name creates the group, subject to the licence's runner-group entitlement. |
--labels <a,b> | Comma-separated labels stamped onto enrolled runners — matched by a placement requirement's labels demand. |
--ttl <d> | Token lifetime (Go duration, e.g. 30m, 24h; default 1h). Redemptions after expiry are refused. |
--ephemeral | Enrolled runners deregister after one job — for scale-to-zero or per-job runners. |
--max-uses <n> | Maximum redemptions (default 0 = unlimited within the TTL; 1 = single-use/JIT). |
Output
The token value alone on stdout, ready to capture:
TOKEN=$(opschain admin runner-token create --server https://opschain.example.com --group secure --max-uses 1)
-o json|yaml prints token and expires_at as a machine document
instead.
Exit codes
0 minted; 1 the request failed (network, rejected token); 2 usage (no server target, no admin token).
Named errors
a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>'(exit 2)this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login'(exit 2)the server rejected the credential — run 'opschain login' again, or check the admin token(exit 1)
See also
opschain docs cli/admin-runner-token-list— the minted tokens' fingerprints, uses and status.opschain docs cli/admin-runner-group-set— the placement contract the token's group confers.opschain docs fleet-queue— how group and labels decide what enrolled runners are offered.opschain learn 6.1— the runners-and-fleet walkthrough, including enrolment end to end.