Gateway Architecture

Relevant source files

• .env.example
• AGENTS.md
• README.md
• agent/auxiliary_client.py
• agent/onboarding.py
• cli-config.yaml.example
• cli.py
• contributors/emails/mattshapsss@gmail.com
• gateway/assets/status_phrases.yaml
• gateway/display_config.py
• gateway/run.py
• gateway/status.py
• gateway/status_phrases.py
• gateway/stream_consumer.py
• hermes_cli/auth.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/doctor.py
• hermes_cli/gateway.py
• hermes_cli/main.py
• hermes_cli/models.py
• hermes_cli/profiles.py
• hermes_cli/runtime_provider.py
• hermes_cli/setup.py
• hermes_cli/status.py
• run_agent.py
• tests/agent/test_auxiliary_client.py
• tests/agent/test_onboarding.py
• tests/gateway/test_busy_session_ack.py
• tests/gateway/test_discord_document_handling.py
• tests/gateway/test_display_config.py
• tests/gateway/test_document_cache.py
• tests/gateway/test_gateway_command_line_matcher.py
• tests/gateway/test_media_spaced_paths_and_history_dedupe.py
• tests/gateway/test_run_progress_topics.py
• tests/gateway/test_runner_startup_failures.py
• tests/gateway/test_send_image_file.py
• tests/gateway/test_status.py
• tests/gateway/test_status_phrases.py
• tests/gateway/test_stream_consumer.py
• tests/gateway/test_stream_consumer_fresh_final.py
• tests/gateway/test_telegram_documents.py
• tests/gateway/test_verbose_command.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_config_validation.py
• tests/hermes_cli/test_doctor.py
• tests/hermes_cli/test_gateway.py
• tests/hermes_cli/test_gateway_linger.py
• tests/hermes_cli/test_gateway_proc_fallback.py
• tests/hermes_cli/test_gateway_service.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_profiles.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• website/docs/reference/profile-commands.md
• website/docs/user-guide/profile-distributions.md
• website/docs/user-guide/profiles.md

This page documents the GatewayRunner class and its role in orchestrating message routing between messaging platforms and the AIAgent. The gateway runs as a persistent daemon that connects to multiple platforms (Telegram, Discord, WhatsApp, Slack, Signal, etc.) and manages AIAgent instances per session.

Key architectural difference from CLI: While the CLI maintains a single persistent AIAgent instance for a local terminal session, the gateway orchestrates multiple concurrent sessions across different platforms. It instantiates or reuses agents based on incoming MessageEvent data gateway/run.py61-66 Session state is preserved by loading conversation history from a SQLite database (state.db) via SessionDB hermes_state.py7-15

---

System Overview

The gateway consists of three main layers: platform adapters, the orchestration runner, and the core agent logic.

Natural Language to Code Entity Mapping

The following diagram bridges the conceptual messaging flow to the specific Python classes and files responsible for execution.

Sources: gateway/run.py5-14 gateway/run.py158-936 hermes_state.py17-30 gateway/platforms/base.py1-21

Component	Purpose	Location
GatewayRunner	Main orchestration class, manages platform adapters and message routing	gateway/run.py158-936
SessionDB	SQLite-backed session storage with FTS5 full-text search	hermes_state.py17-30
SessionSource	Describes origin metadata (platform, chat_id, user_id, chat_type)	gateway/session.py148-180
AIAgent	The core agent class that executes the conversation loop	run_agent.py17-21
GatewayStreamConsumer	Bridges sync agent callbacks to async platform delivery for progressive edits	gateway/stream_consumer.py83-140
DeliveryRouter	Routes messages to platform adapters for delivery	gateway/run.py98-100
BasePlatformAdapter	Abstract base class for all platform-specific message handling	gateway/platforms/base.py21-25

---

GatewayRunner Lifecycle

Initialization and Agent Cache

The GatewayRunner manages a pool of AIAgent instances using an LRU cache to prevent memory exhaustion in long-lived daemons.

• Cache Tuning: The cache is capped at 128 agents (_AGENT_CACHE_MAX_SIZE) gateway/run.py78
• Idle Expiry: An idle TTL of 3600 seconds (1 hour) is enforced via _AGENT_CACHE_IDLE_TTL_SECS; agents inactive for this duration are evicted gateway/run.py79
• Session Watcher: A background task (_session_expiry_watcher) periodically scans and prunes stale agents from memory gateway/run.py76-77

Sources: gateway/run.py73-80

Startup and Process Management

The gateway startup sequence involves PID management and platform initialization.

Sources: gateway/run.py27-42 hermes_cli/gateway.py84-161 gateway/status.py66-70

Notable startup behaviors:

• Process Tracking: The system tracks the gateway process via a PID file located at {HERMES_HOME}/gateway.pid gateway/status.py66-70
• Windows Venv Patching: On Windows, _ensure_windows_gateway_venv_imports() ensures the Hermes venv packages are visible even if launched via pythonw.exe to avoid missing dependencies gateway/run.py160-191
• Atomic Locking: Uses acquire_gateway_runtime_lock() to prevent multiple gateway instances from running in the same profile simultaneously gateway/status.py150-160

---

Message Routing and Processing

Session Identity and Security

Incoming messages are mapped to sessions using a deterministic session_key.

1. Session Key Construction: Derived via build_session_key(source), typically formatted as agent:main:<platform>:<chat_id> gateway/session.py105-107
2. Path Safety: The gateway rejects session keys that contain parent traversal (..) or unsafe characters to prevent filesystem escape gateway/session.py108-120
3. Session Expiry: A freshness window (default 1 hour) is checked via auto_continue_freshness_window(). If a session is older than this window, the gateway may force a fresh start depending on the SessionResetPolicy gateway/session.py31-57
4. Allowlist Filtering: The gateway enforces an allowlist of authorized users or chats via is_source_allowed() before processing messages gateway/run.py105-110

Sources: gateway/session.py31-120 gateway/run.py105-110

Progressive Streaming

The GatewayStreamConsumer handles real-time delivery of tokens.

• Sync-to-Async Bridge: Receives synchronous on_delta() callbacks from the agent worker thread and queues them for an asyncio task gateway/stream_consumer.py4-9
• Rate Limiting: Buffers tokens and enforces an edit_interval (e.g., 1.0s) to avoid platform rate limits (flood control) gateway/stream_consumer.py55-60
• Reasoning Tags: It recognizes reasoning tags like <think> or <thought> to handle internal model deliberation separately from user-facing content gateway/stream_consumer.py102-112
• Fresh Final Message: For slow-streaming reasoning models, it can deliver the final response as a fresh message instead of an edit if the preview has been visible for a long duration, ensuring the timestamp reflects completion gateway/stream_consumer.py61-68

Sources: gateway/stream_consumer.py4-112

---

Service Integration and Cron

Cron Scheduler Integration

The gateway serves as the primary delivery vehicle for scheduled tasks.

• Delivery Logic: When a cron job triggers, it invokes the gateway's DeliveryRouter to send results back to the original SessionSource gateway/session.py148-156
• Persistence: Scheduled task metadata is managed via hermes_cli/main.py cron subcommands hermes_cli/main.py17-20

Sources: gateway/session.py148-156 hermes_cli/main.py17-20

Service Management and Restarts

• Graceful Restart: The gateway uses specific exit codes to signal its supervisor. GATEWAY_SERVICE_RESTART_EXIT_CODE (75) triggers a service restart by systemd or launchd hermes_cli/gateway.py33-37
• Drain Timeout: During a restart, the gateway can wait for active agent runs to finish before exiting, controlled by DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT hermes_cli/gateway.py33-40
• Systemd Integration: On Linux, the CLI manages user-scope systemd units (hermes-gateway.service) and handles daemon-reload automatically when units are updated hermes_cli/gateway.py107-127
• Watchdog Support: Supports systemd watchdog heartbeats to ensure the gateway hasn't hung, configured via gateway.systemd_watchdog_seconds gateway/config.py153-160

Sources: hermes_cli/gateway.py33-127 gateway/config.py153-160