opschain admin runner drain
Included from Basic tier
opschain admin runner drain <runner-id>
Drains one runner (the v2 RunnerService.SetRunnerDraining RPC): it finishes the steps
it already holds and is offered nothing new. The drain is a durable flag on
the registration — it survives runner and server restarts — and stays in
force until opschain admin runner resume lifts it. Draining never cancels
or reassigns the in-flight work; it only stops new offers.
While the drain is the reason queued work cannot dispatch, the fleet queue
reads it honestly: entries park with every eligible runner is draining
rather than hanging silently. In admin runners list the runner shows
draining while it still holds jobs, then quiesced once idle.
The drain takes effect on every server replica within a dispatch tick: a
drained runner's parked poll is never matched to new work, so the offers
go to the undrained runners without first bouncing off the drained ones.
An idle drained runner keeps polling, but each poll is held for the full
poll window (50 s by default) and answered empty — its last seen in
admin runners list advances once per window rather than several times a
second.
Drain-then-stop is also the path to retiring a runner: drained and stopped,
its registration can be removed with opschain admin runner forget.
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. |
Output
The server's acknowledgement, as JSON (-o yaml for YAML):
{
"draining": true,
"id": "<runner-id>"
}
An info:runner:drain_changed event records who drained what, visible in
opschain events.
Exit codes
0 drained; 1 the request failed (unknown runner id, network, rejected token); 2 usage.
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-resume— lift the drain.opschain docs cli/admin-runner-group-drain— drain a whole group at once.opschain docs cli/admin-runner-forget— remove the registration once drained and stopped.opschain docs fleet-queue— how a drain reads in the queue's verdicts.