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 (stdio transport)

      ├── Ferricula memory client

      ├── Telemetry dashboard (HTTP :9800)

      └── OllamaProvider / AnthropicProvider

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 Ferricula 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. The MCP stdio server also connects to this port when proxying tool calls.

Telemetry dashboard

The sidecar serves a lightweight telemetry dashboard at http://localhost:9800. It tracks 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"), 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}

Embedded Ferricula

The sidecar embeds the Ferricula memory engine directly. When a Ferricula URL is configured in Settings, the Ghost connects to it for persistent recall. Without configuration, the embedded engine operates in-process with in-memory storage — no data persists between Hyperia restarts.

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.