opschain admin agent halt

packs:agents

opschain admin agent halt <agent-id> --reason <text> [--server <url>] [--auth-token <token>]

Emergency-halts one agent (v2 AgentService.HaltAgent) — the per-agent break-glass scalpel. A halt is a hard stop, not a graceful drain: the durable halt flag flips, the agent's channel and in-flight proxied sessions are severed immediately, and every credential of the agent is refused until an explicit opschain admin agent halt-resume. It is reversible by design — no key tombstone — which is what distinguishes it from revoke.

The halt is break-glass audited: the reason and the acting administrator are recorded on the agent's timeline (opschain admin agent activity), and the fleet views read the agent as halted with the reason shown in opschain admin agent show.

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

Flags

Flag	Meaning
--reason <text>	Break-glass reason, recorded on the audit event. Required — and it must be non-blank: the server refuses a whitespace-only reason.
--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):

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

Exit codes

Code	Meaning
0	The halt was applied.
1	The server refused or failed the request (blank reason, rejected admin token, unknown id).
2	Usage — the reason flag not set, wrong arguments, or no server / admin token resolvable.

Named errors

• required flag(s) "reason" not set — exit 2.
• a reason is required: the halt verb is break-glass audited — the server's refusal of a whitespace-only reason, 422, exit 1.
• 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.

Example

opschain admin agent halt 01999a7e-… --reason "suspected credential leak"

See also

• opschain docs cli/admin-agent-halt-resume — lift the halt.
• opschain docs cli/admin-agent-revoke — the irreversible alternative.
• opschain docs cli/admin-agent-activity — where the audited reason lands.