opschain admin agent instances

packs:agents

opschain admin agent instances <agent> [--filter <column>[!]=<value>]... [--server <url>] [--auth-token <token>]

Lists one agent's instances — its running processes — grouped by release and lane (v2 AgentService.ListAgentInstances). An agent is the logical identity: the per-project code the service account, owner, trust grants and recommendations attach to. Each instance is one process of it: a fleet member with its own keypair, bound at enrolment to the release it runs (with the release's current stage cached on the instance), labelled with the lane that routes work to it. A second state directory started with the same code enrols a second instance; a release rollover moves the instances of one lane to another release; retired instances stay listed and marked.

<agent> is the agent's member id (any instance's ID from opschain admin agents list), <project>/<code>, or a bare code when exactly one project holds it.

RELEASE      LANE    INSTANCE                              MEMBER        STAGE  ONLINE  LAST SEEN             STATE
felix@2.0.0  stable  01a1aecc-175c-7572-b3c4-49d2dd1dec76  ocr_FeodwmG…  prod   ✓       2026-11-06T13:58:04Z  ready
felix@2.0.0  stable  01a1aecc-1795-7c21-9a18-0101dabdc665  ocr_JWhTz8U…  prod   ✓       2026-11-06T13:58:05Z  ready
felix@2.1.0  shadow  01a1aecc-17d0-7a1c-8c2e-5b1f0c6d9e01  ocr_Q2mRv7k…  test   ✓       2026-11-06T13:58:05Z  ready

• RELEASE / STAGE — the release the instance enrolled from and the release's CURRENT promotion stage: cached on the instance at enrolment and rewritten on every live instance of the release when it is promoted, retired or revoked (and when a rung is renamed); - for an instance that declared no release.
• LANE — stable (the default dispatch target), shadow (receives the same dispatch as stable, every write forced to the advise tier), canary, or a label the operator chose. A blue-green rollover's green lane (<lane>-green by default) holds the target release's instances before the flip and the old ones after it — the serving lane's label always names the instances dispatch lands on; opschain admin agent rollover show renders both lanes with which one serves.
• INSTANCE — the durable instance id, kept across re-enrolment and release restarts; MEMBER the fleet member (keypair) the instance currently holds, the id the per-member verbs take.
• STATE — retired (forgotten, revoked or replaced), halted, draining (finishing in-flight work, nothing new dispatched — a rollover in progress), ready, or -.

Flags

Flag	Meaning
--filter <column>[!]=<value>	Keep only rows matching the term (repeatable; terms AND). Columns are the printed table headers lowercased (spaces/dashes fold to _); * wildcards match the whole cell case-insensitively, != negates, commas mean any-of. Applied client-side. Grammar: opschain docs cli.
--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.

-o json|yaml prints the raw instance rows (key fingerprint, release id, created and retired timestamps included).

Exit codes

Code	Meaning
0	The instances were printed (an agent with none prints just the header).
1	The server refused or failed the request (a rejected credential, an unknown agent).
2	Usage — wrong arguments, or no server / admin token resolvable.

See also

• opschain docs cli/admin-agent-rollover — move a lane to another release; cli/admin-agent-rollover-show for the lanes of an open rollover.
• opschain docs cli/admin-agents-list — the fleet view, one row per instance.
• opschain docs agent-plane — instances, lanes and routing.