HHermes Explained

Interfaces

Gateway

A persistent service layer that lets remote channels and desktop clients talk to Hermes.

Importance 5/57 backlinks1 source refs

Gateway

What it is

A persistent service layer that lets remote channels and desktop clients talk to Hermes.

In plain terms

Think of the gateway as mail forwarding set up on your old address: letters keep arriving and get redirected automatically, even with nobody standing at that mailbox once the desktop app has locked up for the night. Messages from Telegram, WhatsApp, Discord, and other channels arrive the same way, get sorted into whichever ongoing conversation they belong to, and get handed off to the same kind of agent that would have answered had someone been sitting at a keyboard.

Why it matters

Staying reachable even when nobody has the desktop app open is what a gateway provides — a persistent service that remote channels like Telegram, WhatsApp, and Discord, plus mobile clients, connect through. Without it, every platform integration would need its own always-on process; with it, they share one connection layer routing into the same agent runtime. That’s what turns ‘a chat app on a laptop’ into a genuine mobile command center, the exact workflow this concept backs.

How it works

A single class, GatewayRunner (gateway/run.py), owns the whole lifecycle: it starts every platform adapter that’s configured, and behind the scenes keeps a bounded, least-recently-used cache of live agent instances keyed by conversation, evicting ones that have sat idle past an hour rather than spinning up a fresh agent for every incoming message. Plugin-style adapters, including Telegram, WhatsApp, and Discord, don’t need gateway core edited to add a channel — each self-registers into a shared platform_registry (gateway/platform_registry.py) with its own factory function, though a smaller set of built-in platforms are still wired directly into the runner. A stranger messaging the bot for the first time in a DM does get one automatic reply: pairing.py hands back a one-time, time-limited code and tells them to relay it to the bot owner, who has to approve it before that person’s messages ever reach an agent.

A concrete example

Someone new tries messaging a Hermes bot on WhatsApp for the first time, unprompted, in a direct message.

  1. The gateway receives the message but recognizes the sender isn’t on any allowlist yet.
  2. Rather than staying silent, pairing.py replies immediately with a one-time code and asks the sender to pass it along to the bot owner.
  3. The owner approves the request once they receive that code, using the CLI or the equivalent dashboard action.
  4. The next message from that same person now reaches a live agent instance, which the gateway keeps cached for their ongoing conversation rather than rebuilding each time.

How it connects

This note belongs to the Interfaces family. Its closest neighboring concepts are: Dashboard API, Telegram Gateway, Agent Runtime, Personal OS.

Source evidence

  • web_server — Explicit Source Map scope boundary: hermes_cli/web_server.py is outside the approved Core scope.

Workflows

  • Gateway Mobile Command Center
  • Inside Hermes: How the Agent Loop, Context, Memory, Gateways, and Cron Jobs Work Together
  • Mastering Hermes Desktop: From Local Chat App to an Always-On Agent Control Center
  • Scheduling Hermes: How to Build, Inspect, and Control Automated Cron Jobs
  • From Zero to a Personal AI Assistant: Building Hermes on a VPS Without Creating a Mess
  • Ten Underused Hermes Features That Reveal Its Real Power