The Peer Registry: Bots Across Machines

Connections vs the Peer Registry

Hermes provides two systems for working with bots on other machines, and they serve different purposes.

Connections (Settings → Connections) is the Desktop app's multi-machine system. It registers other Hermes backends and makes their bots appear in your shared roster. SSH sources are inventoried without spawning anything on the remote machine, and machines that are momentarily unreachable keep their last-known roster rows rather than vanishing. This is the right system when you are working interactively in the Desktop app.

The Peer Registry is a CLI-based system designed for headless, programmatic bot-to-bot communication. It lets one bot send a direct message to a bot on a remote machine that is running the api_server gateway -- without any desktop UI involved. It is the right system for scripted workflows, bot routines that need to coordinate across machines, and setups where one machine is a headless server rather than a desktop.

Requirements for Peer Registration

For peer registration to work, the remote machine must meet two requirements:

• It must be running the api_server gateway platform -- not the standard desktop backend. The api_server exposes a REST API that the peer commands communicate with.
• A strong API_SERVER_KEY must be set on the peer machine. This key is what your machine uses to authenticate when sending messages.

Your machine stores the peer's key in ~/.hermes/.env using the naming convention HERMES_PEER_<NAME>_KEY. For a peer registered as "spark", the key variable is HERMES_PEER_SPARK_KEY.

Registering and Using a Peer

Register a peer gateway with:

hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>

List registered peers:

hermes peer list

Send a message to the default bot on a peer:

hermes peer dm spark "check disk usage and report back"

Send a message to a specific named bot on a peer:

hermes peer dm spark/researcher "summarize the latest updates in the project directory"

The spark/researcher format targets a specific profile named "researcher" on the peer named "spark". Without the slash and profile name, the message goes to the peer's default bot.

What Happens Automatically After Registration

Once a peer is registered, bot_mode_protocol extends its automatic injection to include the peer. Every bot's canonical Bot Chat session is taught about the peer roster and the hermes peer dm pattern alongside the local roster. The documentation describes this directly: "your bots learn on their own that teammates exist on other machines and how to reach them."

This means you do not need to manually configure each bot to know about the peer. Registration at the system level propagates to every bot's messaging context automatically. A researcher bot that previously only knew about local teammates will, after peer registration, also know it can reach bots on the registered peer machines.

When to Use Each System

Use the Connections UI when you are working in the Desktop app and want to see and interact with remote bots alongside local ones. Use the Peer Registry when you need bots to coordinate across machines headlessly -- from within routines, scripts, or other automated workflows where no desktop window is involved.

The two systems are not mutually exclusive. A machine can be registered in both, appearing in your Connections roster for interactive use and in the Peer Registry for headless bot-to-bot coordination.