opschain admin agent drain

packs:agents

opschain admin agent drain <agent-id> [--server <url>] [--auth-token <token>]

Marks one agent draining (v2 AgentService.SetAgentDraining). While draining, only the agent's minimum-spec surfaces (healthz, readyz, info, metrics, logs) keep answering; its declared capabilities stop being routed work. An agent holds no queued jobs, so a drain takes effect immediately — the fleet views read the agent as quiesced rather than the runner fleet's draining. The drain is durable (it survives agent and server restarts) and is lifted with opschain admin agent resume.

A whole group can also be draining; the agent then reads quiesced (group) (or quiesced (agent+group) when both apply), and a per-agent resume does not lift the group's drain.

<agent-id> is the agent's member id — the ID column of opschain admin agents list.

Flags

Flag	Meaning
--server <url>	Server base URL. Default: the active context, then 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 for that server.

Output

Always a machine document (JSON unless -o yaml):

{
  "draining": true,
  "id": "01999a7e-…"
}

Exit codes

Code	Meaning
0	The drain was recorded.
1	The server refused or failed the request (including a rejected admin token, or an unknown agent id).
2	Usage — wrong arguments, or no server / admin token resolvable.

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.
• agent <id> is not known to this estate — admin agent verbs take the ocr_ member id from 'opschain admin agents list' (a UUID is usually the identity-side service_account_id, not the member id) — the unknown, revoked or runner id 404, exit 1.
• Any other server refusal is reported as the server answered <code>: <message> — exit 1.

See also

• opschain docs cli/admin-agent-resume — lift the drain.
• opschain docs cli/admin-agent-forget — a drain is one way to satisfy forget's "not online" precondition.
• opschain docs cli/admin-agents-list — where the drain state (and the agent id) shows.