The Broker Fleet Screen
A field guide to every column, status, panel, and action on the dashboard's Broker Fleet screen — installs, statuses, fleet policy, commands, the reported-agents panel, and revoke.
The Broker Fleet screen (Agents › Machines in the app, with Brokers, Agents on machines, Onboard and Manage tabs) is where you manage the brokers joined to your fleets: onboard machines, read their live status, push policy, act on a specific install, and inspect the agents each one reports. This page explains every part of it. The Machines tab appears only when Broker Fleet is turned on for your organization.
The installs table
Each row is one install — a broker on one machine, identified by an install UUID. The columns:
- Host — the machine's hostname.
- Tenant — which tenant owns the install.
- Platform — the machine's operating system and architecture.
- Broker — the broker version it runs.
- Mode —
fleet(heartbeats, takes fleet policy) orpersonal. - Fleet — which fleet it joined, if any.
- Agents — how many active agents the broker reported.
- Last seen — the timestamp of the most recent heartbeat (fleet-mode installs only).
- Status — a live health/liveness readout (below).
Use the status filter and fleet filter to narrow large fleets; the counts at the top (Total, Online, Stale, Offline and Revoked) summarize the current page. A Pending broker counts only in Total.
What each Status means
Status is computed per row from the install's mode, revocation state, and heartbeat age:
| Status | Meaning |
|---|---|
| Online (green) | Fleet-mode; last heartbeat within 3 minutes. |
| Stale (yellow) | Fleet-mode; last heartbeat 3–15 minutes ago. |
| Offline (grey) | Fleet-mode; last heartbeat older than 15 minutes. |
| Pending (grey) | Fleet-mode; registered, but no heartbeat yet. A just-onboarded broker shows this until its first heartbeat, not Offline. |
| Active (green) | Personal-mode install — registered and not revoked. Personal brokers don't heartbeat (liveness is fleet-only), so there's no online/offline to show. |
| Revoked (red) | The install's credential has been revoked; it can no longer talk to the cloud. |
The decision order is: Revoked wins; else if in a fleet, Pending before the first heartbeat, then the heartbeat-age bucket (Online / Stale / Offline); else Active.
Active ≠ actively working
Active is a registration state for a personal-mode install, not a health signal. It only means "registered, not revoked." Liveness (Online/Stale/Offline) exists only for fleet-mode brokers, which heartbeat.
Onboard a broker
The Onboard tab mints a join key (single-use by default, or reusable): click Mint join key, then on the curl tab of the card that appears click Copy (or Copy join URL) and paste the command on the target machine. That whole flow — including macOS/Linux/Windows specifics — is covered in Onboarding a Broker.
The Manage tab has a separate Mint a registration key section: a
one-shot key for registering a single broker by hand, with
caura init --registration-key=<key> on the new host. For onboarding
machines, use the join key on Onboard.
Push fleet policy
Publishes the next policy version to a fleet. The server stamps the
version and effective time; connected brokers receive it live over
their policy stream (an offline broker picks it up on reconnect), with
no restart. The document is JSON — you own the rules array and
categorical_settings; the server owns the envelope. For example:
{
"rules": [
{ "rule_id": "deny-secrets-writes",
"predicate": { "field": "tool", "op": "eq", "value": "write" },
"action": "deny", "severity": "high", "reason": "no secret writes" }
],
"categorical_settings": { "auto_wire_agents": true }
}categorical_settings.auto_wire_agents: true opts the fleet into
zero-touch onboarding of newly detected-but-unconnected agents — each
broker wires them on its own on the next policy apply, without a
per-machine command.
Issue command
Queues a cloud command for one install and delivers it live over the policy stream (an offline broker replays it on reconnect; every command is acknowledged). The dialog has a Command type dropdown and an optional JSON payload:
| Command type | What it does |
|---|---|
agents.rescan | Re-detect the machine's agents, record and issue identities for wired ones. With payload {"wire": true} it also wires any detected-but-unconnected agent (writes its config, with backups) — the way to onboard an agent installed after the broker. |
restart / flush_queue | Reserved command types. Current brokers acknowledge these as unsupported (they're defined in the protocol but not yet implemented broker-side), rather than failing silently. |
Checking the outcome
The dialog queues the command. To see what happened, click History
on the install's row (on the Brokers or Manage tab): Command
history lists each command with its Status (Pending or Acked), when
it was Acked, and the Result the broker reported. On the machine,
caura logs shows the command received / executed / acked, and the
broker's audit log records each execution.
The Reported agents panel
For a selected install, this panel lists the agents the broker reported on its last heartbeat — a snapshot as of last seen, not a live view. Per agent:
- Agent — the agent type (claudecode, codex, cursor, gemini) and its identity UUID.
- Tier — the wiring tier:
full(hooks) orstrong(MCP). - State — Active (identity issued, not revoked) or Tombstoned (revoked/uninstalled).
- Wiring — the integration verdict for an active agent as of that heartbeat: Wired (detected with a clean config plan), Not wired (detected but drifted, or its broker config was stripped), or — (unknown — tombstoned, or the broker couldn't resolve the product).
- First seen / Last reported — when the identity first appeared and the timestamp of the heartbeat that carried it.
Active is identity; Wiring is health
State: Active means the agent's identity is issued and not
revoked — on its own it does not guarantee the agent is currently
wired and able to route memory. The Wiring column is that health
signal: if someone removes an agent's broker config it stays Active
but flips to Not wired. Both are a snapshot as of the last heartbeat,
not a live view — for the real-time verdict, caura status on the
machine remains the source of truth for whether an agent is actually
integrated.
Revoke install
Revokes the install's credential: the cloud hard-rejects its subsequent
calls (403), and a targeted install.revoked event tells a connected
broker to fail closed. Use it when a machine is decommissioned or a
credential may be compromised. It also cancels the install's pending
commands. The row then shows Revoked.
Rotate an install credential
Credential rotation uses the install lifecycle API rather than a queued broker
command. An authorized operator calls
POST /api/v1/admin/installs/{install_uuid}/rotate-credential with
{"tenant_id":"..."}. It requires governance and credential-management
permissions and access to the tenant. CauraOps has the equivalent
internal-token route at /api/v1/fleet-ops/installs/{install_uuid}/rotate-credential.
The response returns the replacement raw_key once. Transfer it to the broker's
existing credential store and restart the broker; this is currently an operator
procedure, described in the credential lifecycle runbook. Keep the install UUID
and tenant unchanged. Fleet membership, claimant and command history remain on
the same install. The dashboard does not offer a queued rotate_credential
command. Original registration credentials cannot replay the replacement key.
How Onboarding Works
The credential model behind broker onboarding — the register-only join key vs the per-machine install credential, how fleets bind, single-use vs reusable keys, where credentials live, the write-ownership boundary, and the security properties. Read this to plan a fleet rollout.
Where Agents Reach and Which Rules They Keep
What the Caura broker can record about the agents on your organization's machines — the programs, hosts, MCP servers and sensitive files their tool calls reach, and whether each call kept the rules you attached a check to. How to turn each on, what is and isn't sent, and where the results show.