# alineo agents
URL: /docs/cli/commands/agents

List running agent sessions, cross-checked against the live OpenSandbox control plane.



```bash
bunx alineo-cli agents [--json]
```

## Flags [#flags]

| Flag     | Description                                                  |
| -------- | ------------------------------------------------------------ |
| `--json` | Print the tracked sessions array as JSON instead of a table. |

## What it does [#what-it-does]

1. Reads the ledger's "Running" entries.
2. Cross-checks each one against a **live** query to the OpenSandbox control plane, not the ledger alone. The ledger's "Running" status only updates on a graceful `agent.close()`/`sb.close()` — a sandbox that crashed, was killed out-of-band, or expired via OpenSandbox's own TTL stays "Running" in the ledger forever with nothing to correct it. Entries that no longer exist on the control plane are silently dropped from the table.
3. Also lists sandboxes actually running on the same OpenSandbox server that **aren't** in this CLI invocation's own ledger at all — labeled "Untracked". This is the normal case for a child sandbox created via `alineo spawn` from inside another sandbox, since that fork uses the child sandbox's *own* internal ledger, not the host's.

## Example output [#example-output]

```
NAME                  SANDBOX ID                              STARTED     EXECS
--------------------------------------------------------------------------------
rlm-master            4af65c3b-24a2-4fd1-999d-918faa9b97fd    2m ago      8

Untracked (not created by alineo, e.g. agent-spawned children):
  6a69afcb-7a00-437a-9819-e032022cc736
```

| Column       | Description                                                                                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NAME`       | The session name from the ledger. Truncated to 19 characters.                                                                                                                                                                                            |
| `SANDBOX ID` | The full sandbox ID — pass this to `alineo prompt`, `alineo stop`, `alineo logs`.                                                                                                                                                                        |
| `STARTED`    | Relative time since the sandbox was created.                                                                                                                                                                                                             |
| `EXECS`      | Number of top-level execs logged against this sandbox in the ledger — **not** the number of individual bash commands a Pi session ran internally, since those happen inside the single long-running bridge process exec, not as separate ledger entries. |

With `--json`, only the tracked (named) sessions are printed — untracked sandbox IDs are omitted from the JSON output.

## Notes [#notes]

* If nothing is running, prints `(no running alineo-tracked sessions — run 'alineo start <spec>' to start one)` instead of an empty table.
* The live control-plane check means `alineo agents` makes a real network call on every invocation — it's not a pure local-file read like `alineo list`.