stackbone agents

stackbone agents reaches the control plane directly and takes no --agent; it is how you discover the installation ids the other commands need. Both verbs are read-only, so neither needs --yes. With --json each one prints the usual { "schema_version": 1, ... } envelope.

Discover the agent installations in your organization. Use the ids and slugs it lists as the --agent target for every other group, such as stackbone runs, stackbone logs or stackbone secrets.

Command	Purpose
`stackbone agents list`	List every agent installation in your organization (incl. local-dev).
`stackbone agents get <slug>`	Read one installation by its slug (id, version, status, tunnel).

kind is cloud for a deployed installation or local for the local-dev install that exists while stackbone dev is running for this project. A local row reports agentVersion as the literal local-dev, because the code it runs lives on your disk and carries no published version.

status is one of provisioning, active, failed, deprovisioning or deprovisioned. It describes the installation record, not whether the box is answering right now. To find out whether a box is reachable, read its contract.

stackbone agents list returns the whole list in one response. It takes no --limit or --cursor, and its payload carries no nextCursor.

JSON payload

Both verbs return the full installation record. The examples below show the fields you read in practice.

// agents list
{ "schema_version": 1, "items": [
  { "id": "inst_123", "agentSlug": "hello-world", "status": "active", "kind": "cloud" }
] }

// agents get <slug>
{ "schema_version": 1, "agent": {
  "id": "inst_123", "agentSlug": "hello-world", "agentVersion": "1.2.0",
  "status": "active", "kind": "cloud", "templateName": "Hello World",
  "templateOwnerOrgSlug": "acme", "localTunnelUrl": null,
  "lastActiveAt": null,
  "createdAt": "2026-05-01T10:00:00Z", "updatedAt": "2026-06-01T10:00:00Z" } }

localTunnelUrl and lastActiveAt are both null on a cloud installation. On a local one they carry the tunnel address and the last heartbeat stackbone dev sent.

Exit codes: 0 ok · 2 auth · 4 not found (unknown slug) · 1 generic. Full table: Conventions → exit codes.