Skip to main content
Channel plugins are standalone subprocesses that adapt communication surfaces into Hiro Server’s message protocol. Channel plugins do not run inside the Hiro Server process. Channel Manager starts them, they connect back over a local WebSocket, and both sides exchange JSON-RPC 2.0 messages carrying UnifiedMessage payloads and channel events.

​
Plugin topology

The plugin owns translation between its external protocol and UnifiedMessage. Hiro Server owns workspace policy, routing, persistence, and agent execution.

​
Responsibilities

External protocol adaptation - The plugin translates between its external surface and Hiro’s UnifiedMessage format. For the built-in devices plugin, the external surface is Hiro Gate. For optional plugins, it can be a third-party messaging platform. Connection to Channel Manager - The plugin process connects to Channel Manager using the WebSocket URL passed at launch. It registers its name, version, and description before it starts normal work. Inbound emission - When the external surface produces a user message, the plugin validates or normalizes it into a UnifiedMessage and emits it to Channel Manager as channel.receive. Outbound dispatch - When Hiro Server sends a message through this channel, the plugin receives channel.send and translates the UnifiedMessage into the external protocol’s send operation. Channel events - The plugin emits channel.event for transport and infrastructure state that is not itself a user message, such as gateway connection state, device connection state, or pairing requests. Lifecycle handling - The plugin receives configuration after registration, starts its external listeners, handles reconnects where applicable, and stops cleanly when Channel Manager sends channel.stop.

​
Runtime lifecycle

Channel Manager appends runtime arguments when it starts a plugin: the local Hiro WebSocket URL, log directory, and log level. The plugin’s entry point uses those values to initialize logging and create PluginTransport.

​
JSON-RPC surface

All plugin-to-server traffic uses JSON-RPC 2.0 over one local WebSocket connection.

​
Plugin to Channel Manager

​
Channel Manager to plugin

​
Persisted configuration

Channel plugin configuration is stored in the channel_plugins table in workspace.db. Runtime PID files live under channels/<channel_name>.pid. Plugin logs are written under logs/channel-<name>.log.

​
Built-in devices plugin

The devices channel plugin is built in and required. It bridges Hiro Server to Hiro Gate. Optional channel plugins follow the same Channel Manager contract, but their external surface is a third-party service instead of Hiro Gate.

​
Channel Manager

Channel Manager owns plugin process lifecycle, WebSocket accept, JSON-RPC dispatch, and the connection registry. See Channel Manager.

​
Communication Manager

Communication Manager receives validated UnifiedMessage payloads from Channel Manager and owns message routing inside Hiro Server. See Communication Manager.

​
Protocol contract

Channel plugins exchange UnifiedMessage payloads with Hiro Server. See Protocol contract and UnifiedMessage reference.

​
See also

Channel Manager

The server-side owner of channel plugin subprocesses and JSON-RPC connections.

Creating channel plugins

Build guide for implementing a new plugin.

UnifiedMessage reference

The message envelope exchanged by plugins and Hiro Server.