devices channel plugin, Channel Manager, Communication Manager, and Agent Manager. The HTTP Server is for same-machine clients that need to inspect or control the already-running workspace server.
The component also exposes the workspace Tool Registry over HTTP. Local clients can discover registered tools with GET /tools and invoke one by name with POST /invoke.
Responsibilities
Local status API -GET /status reports whether the workspace server process is running, the PID, gateway URL, and current gateway WebSocket connection state.
Channel inspection - GET /channels returns connected channel plugin metadata from Channel Manager. This is live runtime state, not just workspace configuration.
Tool Registry API - GET /tools exposes the registered tool schema. POST /invoke executes one registered tool by name with a flat params object.
Character profile API - GET /characters, GET /characters/{id}/profile, and GET /characters/{id}/photo expose local character profile data and images.
Metrics API - Metrics endpoints return the latest metrics snapshot, history, collector status, and runtime metrics configuration.
Lifecycle control - POST /_shutdown and POST /_restart trigger graceful server shutdown or restart through ServerContext, allowing channel plugin subprocesses to be cleaned up.
Main components
FastAPI app
The HTTP app lives inruntime/http_server.py. It defines the local routes and runs under uvicorn inside the same asyncio event loop as the other server components.
ServerContext
The HTTP app reads ServerContext from app state. Lifecycle routes set stop_event and restart flags there; status routes use it to locate workspace files and runtime state.
Tool Registry
server_process.py builds a ToolRegistry, registers all Hiro tools, and attaches it to the HTTP app.
| Route | Purpose |
|---|---|
GET /tools | Return all registered tool names, descriptions, and parameter schemas. |
POST /invoke | Call registry.invoke(tool, params) and return the tool result. |
.execute(...). The HTTP Tool Registry API is an additional local entry point, not the CLI’s normal dispatch path.
Channel info provider
The HTTP app receives a channel info provider from Channel Manager.GET /channels uses it to return connected plugin names, versions, and descriptions.
Metrics Collector
The Metrics Collector is attached to the HTTP app state. Metrics routes read its latest snapshot, history, and configuration.Endpoint groups
| Endpoint group | Routes | Used for |
|---|---|---|
| Status | GET /status | Process and gateway connection status. |
| Channels | GET /channels | Connected channel plugin inspection. |
| Tools | GET /tools, POST /invoke | Tool discovery and tool execution over local HTTP. |
| Characters | GET /characters, GET /characters/{id}/profile, GET /characters/{id}/photo | Local character profile and image reads. |
| Metrics | GET /metrics, GET /metrics/history, GET /metrics/status, POST /metrics/configure | Runtime health snapshots and metrics settings. |
| Lifecycle | POST /_shutdown, POST /_restart | Graceful stop and restart. |
Caller model
| Caller | Uses HTTP Server for |
|---|---|
| Selected CLI commands | Live channel status, metrics, graceful stop/restart. |
| Local tool clients | Discovering and invoking registered tools through /tools and /invoke. |
| Local browser or health checks | Reading /status and other inspection endpoints. |
| Local app surfaces | Reading local workspace runtime data and operational state. |
Processing flow
Related components
Channel Manager
HTTP Server reads connected channel plugin metadata from Channel Manager for/channels. It does not route messages through Channel Manager.
Metrics Collector
HTTP Server exposes Metrics Collector snapshots and configuration over the metrics endpoints.Tool Registry
HTTP Server provides a generic local API over the same tool implementations used by CLI commands, Admin UI services, and agent tooling.ServerContext
HTTP Server usesServerContext for lifecycle control and workspace-scoped runtime access.
See also
Hiro Server components
How the main server components relate to each other.
Channel Manager
The transport manager that owns channel plugins and WebSocket JSON-RPC.
Communication Manager
The internal message router between channels and the agent runtime.
Agent Manager
The assistant runtime that consumes agent-ready messages.