---
title: 'agents'
description: 'Discover the agent installations in your organization and read the ids the other commands target'
position: 13
---

# 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](/docs/cli/reference/conventions#json-output).

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`](/docs/cli/reference/runs),
[`stackbone logs`](/docs/cli/reference/logs) or
[`stackbone secrets`](/docs/cli/reference/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`](/docs/cli/reference/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](/docs/cli/reference/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.

```jsonc
// 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](/docs/cli/reference/conventions#exit-codes).