Ops Dashboard
What each panel in /ops shows, how often it refreshes, and the exact action each control fires against the XEM fleet. Read this before clicking anything in a live deployment, then bookmark it next to the operator guides.
Overview
Dashboard-only surface, session-authed.
Every /ops/* path is a Frontend route guarded
by cookie session plus CSRF token. There is no separate
ops API-key scope, and the paths are NOT
project-scoped (no /:project_id/v1/ prefix).
The active project context comes from the browser session.
For the public, project-scoped execution API, use
/:project_id/v1/exec/* documented in the
XEM overview.
Manage who can reach the dashboard through the project membership management API. Reviewers who lack a project membership but need to act on a specific approval use the out-of-band one-time-link flow described in Approval Workflow.
Dashboard Tabs
The dashboard groups operator surfaces into seven tabs. Refresh cadence is the SSE poll interval defined in Real-time Events unless noted otherwise.
| Tab | What it shows | Primary actions |
|---|---|---|
Overview |
Summary cards: agents online, active executions, pending approvals, queue depth. | Read-only. Click a card to deep-link into the matching tab. |
Operations |
Recent tool executions: invocation ID, tool name, status, duration, executing agent. | Click a row to open the execution detail modal. |
Fleet |
Agent fleet status: hostname, status, tool count, last heartbeat. | Click an agent to drill into /ops/agents/:agentId/workspaces. |
Graph |
Visual topology of workspaces, agents, and tool bindings. Currently an empty hero state; a force-directed renderer is planned and no client-side graph library is loaded today. | None yet. |
Templates |
Reusable prompt templates. | Create at /ops/templates/new; edit at /ops/templates/:id/edit; view at /ops/templates/:id. Deletion, when available, fires from the detail page against the router-side management API. |
Approvals |
Pending human-in-the-loop approval requests plus the last 100 decisions. | Approve or reject inline. See Approval Workflow. |
Agents |
Detailed agent enrollment and configuration; per-agent workspace and chat surfaces. | Drill into /ops/workspaces/:workspaceId and /ops/workspaces/:workspaceId/chats/:chatId. |
Real-time Events
The dashboard connects to /ops/stream for
near-real-time updates via Server-Sent Events. The stream
is implemented as a 2-second database poll loop with a
60-minute maximum connection lifetime; a signal-driven
upgrade is planned. ox.connection.heartbeat
fires every 15 poll iterations (roughly every 30 seconds)
so consumers can detect stalled connections.
/ops/stream is a session-authed Frontend
route and is NOT part of the public API. It cannot be
subscribed to from xeroctl or an external
SDK. The public, project-scoped equivalents are
GET /:project_id/v1/exec/executions/stream
and GET /:project_id/v1/exec/approvals/stream,
which emit x_exec.* event names (not the
ox.* family documented here).
Events emitted on /ops/stream, grouped by family:
| Family | Event | When it fires | Payload |
|---|---|---|---|
| Connection | ox.connection.connected |
Immediately after the SSE handshake. | Empty. |
ox.connection.heartbeat |
Every 15 poll iterations (~30s). | Empty. | |
| Execution | ox.execution.started |
Execution dispatched to an XEM. | Execution row. |
ox.execution.completed |
Execution succeeded. | Execution row with final status. | |
ox.execution.failed |
Execution failed. | Execution row plus error envelope. | |
| Approval | ox.approval.requested |
Approval needed. | Full approval row. |
ox.approval.decided |
Approval resolved (approve or reject). | Minimal: {"id": "<approval_id>"}. |
|
ox.approval.escalated |
Escalation chain advanced. | Approval row with current stage index. | |
ox.approval.timed_out |
Approval expired without resolution. | Approval row. | |
| Agent | ox.agent.online |
Agent connected. | Agent row. |
ox.agent.offline |
Agent disconnected. | Agent row. | |
ox.agent.draining |
Agent entered drain mode. | Agent row. | |
| Discovery | ox.discovery.found |
Component discovered on the mesh. | Component descriptor. |
ox.manifest.updated |
Tool manifest refreshed. | Manifest delta. |
Search
Open the dashboard search palette with
Cmd + K
on macOS or
Ctrl + K
elsewhere. The chord is wired with
KeyboardEvent.code === "KeyK" so non-US layouts
(Dvorak, AZERTY) still land the same physical key.
The backing endpoint
GET /ops/search?q=<query>&type=<agent|workspace|tool>
returns an OpenAI-style list envelope (not a bare JSON
array) with up to 25 matches per bucket. Response shape:
{
"object": "list",
"data": [
{
"type": "agent | workspace | tool",
"id": "<resource id>",
"label": "<display label>",
"snippet": "<matched context>"
}
]
}
Results are post-processed through the dashboard's partial
redactor before being returned, so sensitive substrings in
label and snippet may appear
masked.
Approval Workflow
The Approvals tab is the dashboard-side surface for the workspace approval system. The policy model, risk levels, escalation chains, and delegation rules are defined in XEM approvals. This section covers only the dashboard-specific behaviors.
When a tool execution requires human approval, the request
appears in the Approvals tab and fires an
ox.approval.requested SSE event. Reviewers can
approve or reject from the dashboard or via
xeroctl approvals approve|reject.
Operations whose policy risk class is
irreversible require typed confirmation of the
tool name before approval can be submitted, both in the
dashboard UI and via the
--confirm <tool-name> flag on
xeroctl approvals approve.
Email recipients of approval notifications follow a
separate, one-time-link flow at
/ops/approval/:id, enabled when the
XEROTIER_APPROVAL_LINK_SECRET environment
variable is configured (see
XEM environment variables).
That page is reachable without a dashboard session and is
intended for out-of-band reviewers who are not full project
members.
