Skip to navigation
Daemon

Architecture and Startup

View as Markdown

On narrow screens, scroll diagrams horizontally to read every label.

Process Roles

The harness launches nemo-relay daemon mcp as a Model Context Protocol (MCP) process over standard input and output. This MCP connection keeps a reference open with the daemon. It provides no tools. The daemon’s broker decides whether the user-machine route needs a new worker or can share an existing one.

The MCP process starts a worker on the client computer only when the broker instructs it to. The worker loads the administrator’s system configuration and plugins. Install the daemon as a service; do not install MCP or workers as services.

launch and MCP stdio launch with hook payload WebSocket lifecycle and control launch with protected grant WebSocket lifecycle and control model requests hook requests authenticated requests model requests model requests in pass-through Coding harnessCodex, Claude Code, or Pi MCP lifecycle client Short-lived hook forwarder Daemon and route broker Worker for one machine-user Model provider

Dotted arrows show process startup. Solid arrows show communication; responses return along the request path. Model streams travel back through the worker and daemon to the harness. Hook responses return through the hook forwarder. The harness and hook forwarder do not contact a worker directly.

MCP and worker processes each open a persistent WebSocket control session to the daemon. The daemon pushes route decisions and drain commands on those sessions. Model and hook traffic use separate HTTP connections.

The daemon also exposes read-only HTTP operations for process health and last-known worker assignments. /healthz describes the daemon process and its global deployment mode. /_nemo_relay/v1/workers, /_nemo_relay/v1/workers/status, and the per-worker status path read the broker’s in-memory state without probing workers. Routes without an assigned worker, including pass-through routes, do not appear in worker results.

Local Deployment

One computer HTTPS HTTPS in pass-through HTTP requests launch WebSocket control launch WebSocket control HTTP requests Model provider Harness and hook forwarder MCP client Daemon service127.0.0.1:47632 Per-user worker127.0.0.1:auto port

A system daemon has its own service identity. Each user’s MCP and worker use that user’s identity. Several harness sessions for the same identity share one worker. Different users do not share runtime state. The default worker port is assigned by the operating system; there is no worker service to enable at login.

Initialization Sequence

alt [Route needs a worker] [Another MCP is starting or draining a worker] [Worker is already ready] [Pass-through route] Start with route credential in environment Request challenge and verify daemon identity Signed challenge Signed registration and credential binding LaunchWorker and one-time grant Launch with grant through protected stdin Prove identity and grant, register endpoint Ready over control socket Probe HTTP readiness endpoint Readiness confirmed Route ready WaitForWorker Push next broker decision ReuseWorker UsePassThrough MCP initialize MCP initialized after route is ready Model or hook request with route credential MCP control socket stays open for the session Harness MCP client Daemon Worker

The harness may send its MCP initialize message earlier; Relay does not serve the MCP protocol until it has acquired a usable route. A waiting client follows later broker decisions before completing startup. If worker activation fails after authentication, the route can become pass-through. MCP readiness alone does not prove that a worker is running.

Shutdown and Recovery

First MCP reference Worker ready Activation fails Worker fails One MCP relaunches Last MCP leaves Last MCP leaves Worker exits Empty Activating Ready PassThrough Recovering Draining

The diagram shows the main transitions. Explicit --pass-through never launches a worker. A draining worker cannot be revived; new MCP clients wait for it to exit. Accepted requests have up to two minutes to finish. Workers also stop accepting new requests if they lose authenticated daemon control.

See Identity and Lifecycle for reconnect grace, remote keepalive timing, restart recovery, and all broker states.