The messaging gateway is a background service that connects Hermes Agent to multiple messaging platforms simultaneously. It runs as a long-lived daemon that manages platform adapters, routes messages to per-chat agent instances, and persists conversation history across sessions. The gateway is designed for high availability, featuring a per-session agent cache with LRU eviction and idle TTL to prevent memory leaks gateway/run.py78-79 as well as specialized logic to map raw provider errors or transient network failures into user-safe replies gateway/run.py89-122
For information about the CLI interface, see CLI. For details on how the agent processes conversations, see Core Agent.
The gateway uses a multi-layered architecture where platform-specific adapters normalize incoming traffic into a unified event format, which the GatewayRunner then dispatches to specific AIAgent instances.
This diagram maps high-level gateway concepts to the specific Python classes and files that implement them.
Sources: gateway/run.py5-48 hermes_cli/main.py8-13 hermes_cli/commands.py1-9 gateway/platforms/base.py1-6 hermes_cli/auth.py5-13
| Component | Code Entity | Responsibility |
|---|---|---|
| Gateway Controller | GatewayRunner | Manages adapter lifecycles, session mapping, and LRU agent caching gateway/run.py6-79 |
| Platform Interface | BasePlatformAdapter | Abstract base class defining methods for message sending and media handling gateway/platforms/base.py21-22 |
| CLI Entry Point | hermes gateway | Main CLI command to start, stop, or install the gateway service hermes_cli/main.py8-13 |
| Slash Commands | COMMAND_REGISTRY | Central registry for commands like /new, /model, and /approve hermes_cli/commands.py64-123 |
| Credential Store | auth.json | Persists OAuth tokens and API keys across sessions hermes_cli/auth.py5-6 |
Sources: gateway/run.py6-79 hermes_cli/commands.py64-123 gateway/platforms/base.py21-22 hermes_cli/auth.py1-6
The GatewayRunner acts as the central nervous system. It manages a cache of AIAgent instances, capped by _AGENT_CACHE_MAX_SIZE (default 128) and evicted after _AGENT_CACHE_IDLE_TTL_SECS (1 hour) gateway/run.py78-79
The gateway integrates with the host operating system's service manager via hermes_cli/main.py and hermes_cli/gateway.py:
start, stop, status, install, and uninstall using systemd (Linux) or launchd (macOS) hermes_cli/main.py9-13 hermes_cli/gateway.py108-174_TELEGRAM_NOISY_STATUS_RE filter transient/auxiliary status messages (like compression progress) from human-facing chats to keep logs clean gateway/run.py89-122coerce_systemd_watchdog_seconds gateway/config.py153-191For details on routing, session expiry, and cron integration, see Gateway Architecture.
Sources: gateway/run.py78-122 hermes_cli/main.py8-13 hermes_cli/gateway.py108-174 gateway/config.py153-191
Platform adapters translate platform-specific protocols into a common messaging format. Each adapter is responsible for handling its own network requirements, such as proxy normalization gateway/platforms/base.py24 and message constraints.
| Feature | Implementation Detail |
|---|---|
| Authentication | Leverages ~/.hermes/.env for API keys and ~/.hermes/auth.json for OAuth tokens (Nous, xAI, Spotify, etc.) hermes_cli/config.py1-6 hermes_cli/auth.py176-200 |
| Multiplexing | Supports GATEWAY_MULTIPLEX_PROFILES for multi-profile operator overrides gateway/config.py48-74 |
| Media Routing | Distinguishes between audio, voice, and documents based on platform capabilities (e.g., Telegram's sendAudio vs sendVoice) gateway/platforms/base.py131-151 |
| UTF-16 Limits | Telegram adapters use utf16_len to respect platform-specific message length limits (4,096 units) gateway/platforms/base.py154-166 |
For details on specific adapter implementations, see Platform Adapters.
Sources: hermes_cli/config.py1-6 hermes_cli/auth.py176-200 gateway/platforms/base.py131-166 gateway/config.py48-74
The gateway manages session state and provides a bridge between messaging platforms and the agent's core capabilities.
AIAgent instance that handles the conversation loop and tool execution run_agent.py17-20ContextCompressor to trigger history compression and provides progress notices if opted-in run_agent.py158-161 gateway/run.py165-170cwd, while gateway sessions record nothing (None) to avoid restoring invalid host paths run_agent.py68-81.ogg, .opus, .mp3, .wav, .m4a, and .flac for native audio delivery gateway/platforms/base.py31For details on media caching, idle resets, and formatting, see Session and Media Management.
Sources: run_agent.py17-161 gateway/platforms/base.py31 run_agent.py68-81 gateway/run.py165-170
The gateway implements a strict security model to prevent unauthorized access to the agent's toolsets.
.env files, and sensitive environment variables like LD_PRELOAD or PYTHONPATH are blocked from being set via config tools to prevent code injection hermes_cli/config.py159-171/approve or /deny slash commands in the gateway hermes_cli/commands.py98-101pair (start a pairing flow) or ignore gateway/config.py198-204/whoami allow users to inspect their command access levels (admin vs user) hermes_cli/commands.py123For details on the security model and pairing flow, see Security and Pairing.
Sources: hermes_cli/config.py159-171 hermes_cli/commands.py98-123 gateway/config.py198-204
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.