Inspect live sidecars with firma sidecar status

firma sidecar status lists sidecars started by firma run --sidecar local and reports whether they are healthy. Use the default table for interactive inspection or --json for scripts.

Quickstart

# List all live per-run sidecars.
firma sidecar status

# Check one sidecar.
firma sidecar status --sandbox-id sbx_01j0000000e008000000000001

# JSON output, suitable for scripting.
firma sidecar status --json

# Probe the long-lived daemon sidecar.
firma sidecar status --daemon

Output

Table (default)

SANDBOX_ID                           AGENT        PID     STATE      LISTEN                     UPTIME
sbx_01j0000000e008000000000001      claude-code  42891   running    /run/user/1000/firma/…     00:02:34
sbx_01j0000000e008000000000002      codex        51002   stopped    -                          00:14:08

Columns:

Column	Description
`SANDBOX_ID`	The run’s sandbox identifier.
`AGENT`	Agent associated with the run.
`PID`	Sidecar process ID, or `-` if absent.
`STATE`	`running`, `unhealthy`, `stopped`, or `unknown`.
`LISTEN`	Address used to reach the sidecar, or `-`.
`UPTIME`	Sidecar uptime as `HH:MM:SS`, or `-`.

JSON (`--json`)

firma sidecar status --json

Emits a single JSON array — one object per sidecar. An empty list prints [].

[
  {
    "sandbox_id": "sbx_01j0000000e008000000000001",
    "agent_id": "agt_01j0000000e008000000000001",
    "session_id": "sess-abc123",
    "authority_url": "http://127.0.0.1:50051",
    "policy_bundle_version": "a1b2c3d4",
    "pid": 42891,
    "started_at": "2026-05-18T08:00:00Z",
    "state": "running",
    "listen": "/run/user/1000/firma/run/sbx_01j0000000e008000000000001/sidecar.sock",
    "uptime_secs": 154
  }
]

When a PID is unavailable, table mode renders PID as - and JSON mode emits "pid": null.

Modes

Default: all per-run sidecars

Running firma sidecar status with no extra flags lists every known per-run sidecar. Entries that cannot be read safely are omitted.

`--sandbox-id <id>`: single entry

Targets one sandbox by ID and checks whether its sidecar is reachable. This is useful in scripts that monitor a specific firma run invocation.

Pass the full sbx_... sandbox ID generated by Firma. Malformed IDs are rejected. Find the ID in firma sidecar status --json or the sandbox_id field of an audit event.

If <id> does not match a known sandbox, the result is an empty table (or [] with --json) and the command exits 0.

`--daemon`: long-lived daemon sidecar

Checks the long-lived daemon started by firma sidecar start, rather than a sidecar started for a specific firma run invocation.

STATE semantics

State	Meaning
`running`	The sidecar is running and reachable.
`unhealthy`	The sidecar is running but is not responding.
`stopped`	The sidecar is no longer running.
`unknown`	Firma could not determine the sidecar state.

Exit codes

Code	Meaning
`0`	All listed sidecars are `running` (or list empty).
`1`	Any sidecar is `unhealthy` or `stopped`.
`2`	Internal error; message written to stderr.

An empty sidecar list exits 0 — vacuously, nothing is unhealthy. Wire the 0/1 split into healthchecks, systemd ExecStartPost, or CI gates:

firma sidecar status --json | jq -e 'all(.[]; .state == "running")'

For daemon status, a malformed pidfile is reported as an internal error with exit code 2; it is not treated as evidence that the daemon is stopped.

Stale entries

firma sidecar status removes stale entries for sidecars that are no longer running. If an entry cannot be read safely, Firma leaves it untouched and omits it from the listing.

On Unix, an exited process that has not yet been collected by its owning parent still exists as a zombie. Firma reports that entry as unhealthy and retains its marker directory until the owner collects it; observational status and garbage-collection probes never reap another process’s child.

What’s next

Wrap an agent with firma run — start a managed per-run sidecar.
Start and monitor the daemon (firma sidecar & monitor) — supervise Authority and the daemon Sidecar as one unit.
Run the sidecar standalone — start a Sidecar directly without firma run or firma sidecar start.