DeepBlue Dynamics / Docs / Hyperia / Sidecar & Telemetry

Sidecar & Telemetry

The Rust process that runs alongside Electron — architecture, ports, and telemetry.

Architecture

Hyperia is split into two processes: the Electron renderer (the terminal UI) and the Rust sidecar (hyperia-sidecar). The sidecar handles everything compute-intensive or network-facing — the Ghost agent loop, LLM streaming, MCP server, Ferricula memory, and the telemetry dashboard.

    Electron (renderer)

      ├── Terminal tabs (xterm.js + node-pty)

      ├── Web panes (Chromium webview)

      ├── Sticky notes

      └── ↔ WebSocket bridge → sidecar :9800

    Rust sidecar (hyperia-sidecar)

      ├── Ghost agent loop (streaming LLM + tool execution)

      ├── MCP server (streamable HTTP at /mcp)

      ├── lume (built-in BM25 memory) + optional Ferricula client

      ├── Doctor / telemetry dashboard (HTTP :9800/dashboard)

      └── Anthropic / OpenAI / Gemini / Ollama providers

The sidecar starts automatically when Hyperia launches and shuts down when the app closes. It is a single binary with no runtime dependencies — the full agent stack, including the built-in lume memory engine, is compiled in.

Default port

The sidecar listens on localhost:9800 by default. You can override this with the HYPERIA_PORT environment variable or via config:

{
  "config": {
    "sidecarPort": 9810
  }
}

All internal communication between the Electron app and the sidecar goes through this port. MCP clients connect over streamable HTTP to http://localhost:9800/mcp.

Doctor & telemetry dashboard

The sidecar serves a lightweight dashboard at http://localhost:9800/dashboard. It combines a Doctor view (readiness checks — provider tokens, Ollama reachability, MCP connections, service health) with live telemetry — token usage, tool call counts, model spend estimates, and agent session history.

📊 SCREENSHOT — telemetry dashboard

Open the dashboard in a web pane with open_web_pane(url="http://localhost:9800/dashboard"), or point any browser at it while Hyperia is running.

HTTP API

The sidecar exposes a small HTTP API consumed by both the Electron app and the Ghost agent.

Endpoint	Method	Description
/api/ghost/chat	POST	Send a message to the Ghost agent. Returns SSE stream of events.
/api/ghost/reset	POST	Clear the Ghost session's message history.
/api/ghost/status	GET	Returns current agent state, token counts, and model info.
/api/telemetry	GET	Returns raw telemetry data for the current session.
/api/bridge/*	GET/POST	WebSocket bridge for Electron ↔ sidecar communication.
/health	GET	Returns `{"ok": true}` if the sidecar is running.

Ghost chat stream format

The /api/ghost/chat endpoint streams SSE events. Each line is a data: {...} JSON object:

data: {"type": "text_delta", "text": "Running ls..."}
data: {"type": "tool_call", "name": "terminal_run", "input": {"command": "ls"}}
data: {"type": "tool_result", "content": "file1.txt  file2.txt"}
data: {"type": "message_stop", "stop_reason": "end_turn"}
data: {"type": "usage", "input_tokens": 412, "output_tokens": 88}

lume & Ferricula

The sidecar includes lume, a built-in local BM25 index over your shell history and sticky notes. It's on by default, runs in-process, and stores its state under ~/.hyperia/lume/ — no configuration, no external service.

Ferricula is an entirely optional external memory service. Point Hyperia at a Ferricula URL in Settings (Settings → Memory → Ferricula URL) and the Ghost uses it in addition to lume for semantic recall across sessions. The sidecar talks to Ferricula over HTTP and gracefully no-ops when it's unreachable — Hyperia keeps working with lume alone.

Logs

The sidecar logs to stderr, which Hyperia captures internally. You can read recent log output via the sidecar_logs MCP tool or inspect it from the Settings window.

To run the sidecar manually with verbose logging:

# macOS / Linux
RUST_LOG=debug hyperia-sidecar

# Windows
set RUST_LOG=debug && hyperia-sidecar.exe

Crash loop protection

Hyperia tracks sidecar restart attempts. If the sidecar crashes more than 3 times within a short window, Hyperia stops trying to restart it and shows an error in the status area. This prevents runaway crash loops from spinning the CPU.

Common causes of sidecar failure on startup:

• Port conflict — another process is already on port 9800. Change sidecarPort in config.

• Another Hyperia instance — only one sidecar can run per port. Close the other window first.

• Missing binary — the sidecar wasn't bundled correctly. Reinstall Hyperia.