Connect Hermes Through the Experimental Relay Connector

Hermes Relay is an experimental connector system, not another chat platform. A separate connector owns platform bot tokens and sockets. The Hermes gateway dials outward over one authenticated WebSocket, receives normalized inbound events, and sends normalized actions without storing the underlying platform credentials.

Decide whether Relay fits

Relay is useful for managed or multi-tenant hosting, shared connector infrastructure, or gateways that should not hold Discord, Telegram, Slack, or WhatsApp secrets. A self-hosted bot with direct credential ownership should normally use the native adapter instead.

Enrollment redeems a single-use token for a per-gateway secret. After enrollment, restart the gateway so the new relay settings are loaded. The connector advertises supported operations—streaming, edits, media, prompts, reactions, threads, typing, and metadata—during the handshake. Hermes must degrade safely when an operation is absent.

Deployment checklist

• Treat Relay as experimental and pin compatible versions.
• Obtain enrollment material through a trusted provisioning path.
• Use TLS and an outbound-only connector URL.
• Restart after enrollment and confirm one authenticated handshake.
• Review the advertised capability descriptor.
• Test buffering, replay, and revocation without leaking platform tokens.

Pitfalls

A successful WebSocket connection does not guarantee every native feature. Never assume buttons, threads, edits, or media are available without the connector descriptor. Enrollment tokens are single-use and tenant-bound. A post-handshake authentication close can indicate revocation and should stop reconnection instead of creating an endless loop. Keep wake pokes payload-free.

Verification steps

1. Enroll the gateway and confirm secrets are stored without printing them.
2. Restart and verify the connector handshake and fronted-platform list.
3. Send one inbound and outbound message on each configured platform.
4. Exercise one unsupported operation and confirm a safe text fallback.
5. Disconnect the gateway, enqueue a message, reconnect, and verify ordered single delivery.
6. Revoke the gateway and confirm it stops retrying after an authenticated revocation.

See the official Hermes Relay guide for current enrollment, capability, buffering, and troubleshooting details.