7.9 KiB
Per-agent web server: stats, screen and endpoints
What each agent's harness serves on its own port: the stats page, the GUI
screen page, the stream hivectl watch reads, the dashboard card's state and
the extra proxies. The operator's overview is
the agent web server. The agent has no
terminal page of its own: the live terminal and its message box are in the swarm
UI.
Per-agent endpoints
The agent has no login flow of its own. An agent without credentials
reports needs_login_idle, the operator logs in from the swarm UI, and the
credentials arrive from the swarm secret store.
GET /api/state—{label, dashboard_port}: the agent's name, for the stats and screen pages' titles and the screen's login, and the hive dashboard's port for their way back.GET /api/dashboard-state— lean snapshot of agent-owned fields fetched once per running agent by the dashboard's container row to get fresh values without relying on hive-c0re's periodic file-reads. Returns{ status_text?, status_set_at?, rate_limited, links }. Only called when the container is running; skipped (muted badges) when stopped. Also accessible via the gateway at/agent/<name>/api/dashboard-state.GET /api/stats?window=24h|7d|30d|all— time-bucketed turn analyticsSnapshotconsumed by the/statspage.allranges from the earliest recorded turn with an adaptive bucket width.GET /icon— agent's icon asimage/svg+xml. Returns/etc/hyperhive/icon.svg(set viaservices.hyperhive.agent.iconinagent.nix) when present, otherwise 404 — there is no server-side default. Consumers (the dashboard container row) hit/iconoptimistically and fall back client-side on load failure to the frontend-bundled/favicon.svgrather than probing first.GET /screen— VNC viewer page (minimal RFB-over-WebSocket renderer — deliberately thin, just enough to display the desktop + forward pointer + keyboard. A production-grade viewer would vendor noVNC; this file ships the minimal in-tree variant). Only accessible whenservices.hyperhive.agent.gui.enable = truein the agent'sagent.nix; the harness shows a 🖥 screen link in the state row whengui_vnc_portis present. Controls:⤢ fitCSS-downscales the canvas to the window viarelayoutCanvas()setting explicit pixel dimensions on the canvas — not CSSmax-width/max-height, because a flex item's automatic minimum size (min-width: autoresolves to the canvas's intrinsic framebuffer resolution) silently clampsmax-*back up, making fit mode a no-op that just centred + clipped the oversized canvas. The fit-mode rules pin the canvas withflex: none; min-width: 0; min-height: 0so the JS-set size sticks.⤡ match sizesends an RFBSetDesktopSizerequest so the server (weston) changes its real output resolution to the window dimensions; enabled once the server advertises theExtendedDesktopSizepseudo-encoding (-308rect in the header). Fit-mode state persists inlocalStorage(screen-fit); default is on.sendPointerrescales pointer coordinates so presses land on the right pixel regardless of CSS scale.GET /screen/ws— raw RFB byte relay: proxies WebSocket frames to the weston VNC server at127.0.0.1:<vnc_port>. Transparent to any RFB variant. VNC port comes from theHIVE_GUI_VNC_PORTenv var (a fixed port set on the harness service whenservices.hyperhive.agent.gui.enable; seeweston-vnc.nix).GET|POST /extra/<name>/…— extra web proxies declared viaservices.hyperhive.agent.extraWebProxiesinagent.nix(serialised to theHIVE_EXTRA_WEB_PROXIESenv var as a JSON object{"<name>": "<upstream_url>"}). Each entry mounts a transparent reverse-proxy at/extra/<name>/that forwards every request (method, headers, body) to the configured upstream, strips hop-by-hop headers on both sides (repeated response headers such as twoSet-Cookielines are all forwarded), and buffers the full response body (MVP — SSE connections will appear as one large response rather than streaming). The/extra/namespace ensures user-declared proxies can never conflict with native agent endpoints. Upstream values are either anhttp(s)://URL (forwarded viareqwest) or a Unix domain socket, spelledunix:<path>(for exampleunix:/run/myapp/http.sock) — dialed directly with a raw HTTP/1.1 client per request, sincereqwesthas no UDS transport. Implemented inweb_ui/proxy.rs.GET /events/stream— the live SSE stream of classified terminal rows, whichhivectl watchreads. The swarm UI shows the same rows from the swarm queue.GET /redirects to/stats.
Bus events on /events/stream:
status_changed { status }—online/rate_limited/needs_login_idle. Drives the alive-badge. The harness setsrate_limitedwhen it detects a 429 response and clears it when the retry sleep expires.model_changed { model }— drives the model chip. The harness emits it when it applies or clears a swarm value.effort_changed { effort }— drives the effort chip. The harness emits it when it applies or clears a swarm value.token_usage_changed { ctx: TokenUsage, cost: TokenUsage }— drives the ctx + cost badges. Emitted fromBus::record_turn_usageat turn-end;ctxis the last inference's usage (current context size),costis the cumulative across every inference (theresultevent's totals).turn_state_changed { state, since_unix }— drives the state badge (idle/thinking/compacting).
Stats page
GET /stats is a per-agent page (served by the
harness, linked from each dashboard container row). Turn analytics, read-only, from
/state/hyperhive-turn-stats.sqlite. GET /api/stats?window= 24h|7d|30d|all returns a time-bucketed Snapshot; the page renders
it with Chart.js (bundled into stats.js via esbuild — no CDN
dependency). Charts: turns, duration (p50 · p95 · avg), context
tokens, token cost per bucket, a turns-by-model stacked bar
(model choice drives token cost, so it sits directly under the
cost chart), doughnuts for tool / wake-source / result mix, and a
result-trend stacked bar — per-bucket result_counts so
error / rate-limit / compaction outcomes are visible over time
(the doughnut shows only the window total).
A favorite tools doughnut shows the most-run shell commands —
normalised bash_commands heads written per bash task by the
hive-bash-daemon capture: the basename of the first real command,
looking past cd repo && prefixes, env-assignments, and
prefix-runners like sudo / env (so cd /repo && cargo build
records cargo, not cd). Read via bash_breakdown; the card
stays hidden until the agent has run a bash command (a missing
bash_commands table degrades to an empty list), so it never
renders an empty chart.
A summary chip row carries window totals, plus two
token-efficiency chips derived from the bucket sums: cache
hit-rate (cache_read over all input-side tokens) and
tokens/turn. When reminder_stats is present (fetched via
ReminderRollup RPC and merged into the snapshot in
web_ui/stats.rs::api_stats) three more chips appear: reminders
scheduled / delivered / pending for the window. When the
per-session capture has data, a first-turn ctx chip shows the
input tokens of the most recent fresh claude session's first turn —
a proxy for system-prompt + AGENTS.md sprawl (a fresh session's first
turn pays the full static prefix uncached). It's derived in stats.rs
(first_turn_ctx: the first turn, ORDER BY started_at LIMIT 1, of
the latest sessions row in the window) and stays out of the JSON
until the sessions / turn_stats.session_id capture has rows — so
the chip stays hidden on older dbs (inert-until-capture).
stats.rs opens the sqlite db read-only and degrades to an
empty snapshot on any error — the page is decorative, never
authoritative.