Skip to main content
Hermes is an external agent runtime. Relay supplies the contact identity, conversation, events, and message API; Hermes continues to own the model, tools, memory, and process. Relay ships a Hermes platform plugin using the same mechanism as Hermes’ Telegram and Discord channels. It long-polls Relay’s event log (no webhook, no public URL, works behind NAT), replies with idempotent sends, and streams long answers natively through Relay’s draft lifecycle. Install it from the Relay repo:
1

Install the plugin

Copy the plugin into your Hermes install’s platform directory:
git clone --depth 1 https://github.com/companion-inc/relay /tmp/relay
cp -r /tmp/relay/integrations/hermes/relay \
  ~/.hermes/hermes-agent/plugins/platforms/relay
2

Create the agent and configure the token

In the Relay app choose Create your own, name your contact, and copy its one-time Agent Token. Then add to ~/.hermes/.env:
RELAY_AGENT_TOKEN=relay_agt_live_...
# optional
RELAY_API_URL=https://api.relayapp.im
RELAY_HOME_CHANNEL=cnv_...   # cron / notification delivery target
3

Restart the gateway

hermes gateway restart   # or: systemctl --user restart hermes-gateway
The gateway log shows [Relay] Connected as @yourhandle (agt_…).
4

Pair yourself

Text your new contact in Relay. Hermes replies with a one-time pairing code; approve it on the machine running Hermes:
hermes pairing approve relay <CODE>
From then on you’re recognized automatically, and gateway slash commands (/whoami, /platform list) work inside the Relay conversation.
Keep RELAY_AGENT_TOKEN in the Hermes process environment or its secret manager. It authenticates as the Relay contact and should not be committed to source control.

​
Pick a delivery mode

Like Telegram’s Bot API, Relay offers two interchangeable ways to receive messages. Use exactly one at a time:
  • Long polling (GET /v1/events?timeout=25): no public inbound URL required. Right for machines behind NAT, home labs, and local development. This is what the Hermes plugin uses.
  • Webhook (POST /v1/webhook): Relay pushes signed events to your HTTPS endpoint. Right for hosted runtimes with a public URL.
Both carry the same event envelope and both are at-least-once: deduplicate by event_id either way.