# 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](../../2-handbook/agents/web-page.md). 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//api/dashboard-state`. - `GET /api/stats?window=24h|7d|30d|all` — time-bucketed turn analytics `Snapshot` consumed by the `/stats` page. `all` ranges from the earliest recorded turn with an adaptive bucket width. - `GET /icon` — agent's icon as `image/svg+xml`. Returns `/etc/hyperhive/icon.svg` (set via `services.hyperhive.agent.icon` in `agent.nix`) when present, otherwise **404** — there is no server-side default. Consumers (the dashboard container row) hit `/icon` optimistically and fall back client-side on load failure to the frontend-bundled `/favicon.svg` rather 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 when `services.hyperhive.agent.gui.enable = true` in the agent's `agent.nix`; the harness shows a 🖥 screen link in the state row when `gui_vnc_port` is present. Controls: `⤢ fit` CSS-downscales the canvas to the window via `relayoutCanvas()` setting explicit pixel dimensions on the canvas — _not_ CSS `max-width/max-height`, because a flex item's automatic minimum size (`min-width: auto` resolves to the canvas's intrinsic framebuffer resolution) silently clamps `max-*` back up, making fit mode a no-op that just centred + clipped the oversized canvas. The fit-mode rules pin the canvas with `flex: none; min-width: 0; min-height: 0` so the JS-set size sticks. `⤡ match size` sends an RFB `SetDesktopSize` request so the server (weston) changes its real output resolution to the window dimensions; enabled once the server advertises the `ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header). Fit-mode state persists in `localStorage` (`screen-fit`); default is on. `sendPointer` rescales 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 at `127.0.0.1:`. Transparent to any RFB variant. VNC port comes from the `HIVE_GUI_VNC_PORT` env var (a fixed port set on the harness service when `services.hyperhive.agent.gui.enable`; see `weston-vnc.nix`). - `GET|POST /extra//…` — **extra web proxies** declared via `services.hyperhive.agent.extraWebProxies` in `agent.nix` (serialised to the `HIVE_EXTRA_WEB_PROXIES` env var as a JSON object `{"": ""}`). Each entry mounts a transparent reverse-proxy at `/extra//` that forwards every request (method, headers, body) to the configured upstream, strips hop-by-hop headers on both sides (repeated response headers such as two `Set-Cookie` lines 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 an `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket, spelled `unix:` (for example `unix:/run/myapp/http.sock`) — dialed directly with a raw HTTP/1.1 client per request, since `reqwest` has no UDS transport. Implemented in `web_ui/proxy.rs`. - `GET /events/stream` — the live SSE stream of classified terminal rows, which `hivectl watch` reads. 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 sets `rate_limited` when 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 from `Bus::record_turn_usage` at turn-end; `ctx` is the last inference's usage (current context size), `cost` is the cumulative across every inference (the `result` event'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.