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.

runtimeUrl is where the row's runtime answers: the dev tunnel on a local installation, the registered deployment on a cloud one. It is null when there is nowhere to send a call. A local row with null has no stackbone dev session running. A cloud row with null has no deployment registered yet, and stackbone link registers one. In human mode this is the last column of agents list, which shows - when the value is null.

stackbone agents list returns the whole list in one response. It takes no --limit or --cursor, and its payload carries no nextCursor. Its human output ends each row with where that installation answers: the tunnel address of a local row, the registered box of a cloud row, or - when there is neither. The id of a cloud row is what stackbone link --installation takes when you register the box that serves it.

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",
    "runtimeUrl": "https://hello-world.acme.example" /* or null when nothing answers for this row */ }
] }

// 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, "runtimeUrl": "https://hello-world.acme.example",
  "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.