Multi-Platform Gateway Architecture for Hermes Agent

🔴 Advanced⏱ 14 min read📅 2026-04-14👤 HermesAgent Community

The Multi-Platform Challenge

When you connect Hermes to Telegram, Discord, and Slack separately, each runs as an isolated process. This creates challenges:

Duplicated context — The same question answered differently on each platform
Memory fragmentation — Long-term memories don't sync across platforms
Resource waste — Each connection maintains its own model instances
Inconsistent behavior — Different configurations per platform

The solution is a unified gateway — a single Hermes instance that routes messages from all platforms through one intelligence layer.

Gateway Architecture Overview

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Telegram │ │ Discord │ │ Slack │ │ Adapter │ │ Adapter │ │ Adapter │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────────┐ │ Message Router │ │ ┌─────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Auth & │ │ Session │ │ Rate Limiter │ │ │ │ ACL │ │ Manager │ │ │ │ │ └─────────┘ └──────────┘ └──────────────────┘ │ └──────────────────────┬───────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────┐ │ Hermes Agent Core │ │ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │ │ │ AI Model │ │ Memory │ │ Skills Engine │ │ │ │ Router │ │ System │ │ │ │ │ └──────────┘ └──────────┘ └────────────────┘ │ └──────────────────────────────────────────────────┘

Setting Up the Gateway

Configuration

Enable gateway mode in your config:

# ~/.hermes/config.yaml gateway: enabled: true port: 8080 # Internal API port mode: "unified" # unified | isolated # Unified session strategy session_strategy: "per-user" # per-user | per-platform | shared # per-user: Same user gets same context across platforms # per-platform: Each platform has independent sessions # shared: Everyone shares one session # User identity mapping identity_mapping: enabled: true # Map the same person across platforms users: - name: "Alice" telegram_id: 123456789 discord_id: "987654321098765432" slack_id: "U01ABCDEF" - name: "Bob" telegram_id: 987654321 discord_id: "123456789098765432" # Platform adapters adapters: telegram: enabled: true bot_token: "7123456789:AAH..." priority: 1 # Lower = higher priority for notifications discord: enabled: true bot_token: "MTIzNDU2Nzg5MDEy..." priority: 2 slack: enabled: true bot_token: "xoxb-..." signing_secret: "..." priority: 3 # Routing rules routing: # Auto-forward critical alerts to all platforms broadcast_alerts: true alert_channels: telegram: [123456789] # User IDs discord: ["1234567890123456789"] # Channel IDs slack: ["C01234ABCDE"] # Channel IDs # Default model per context model_routing: code_review: "anthropic/claude-3.5-sonnet" quick_answers: "openai/gpt-4o-mini" default: "anthropic/claude-3.5-sonnet"

Starting the Gateway

# Start all adapters through the gateway hermes gateway start

🌐 Hermes Gateway started! Port: 8080 Mode: Unified Session strategy: per-user Adapters: ✅ Telegram (@my_hermes_bot) ✅ Discord (Hermes AI#1234) ✅ Slack (My Company) Identity mappings: 2 users Routing rules: 3 active Gateway ready. All platforms connected.

Message Routing

How Messages Flow

When a message arrives from any platform:

Adapter receives the raw message and normalizes it

Auth & ACL checks if the user is authorized

Identity resolver maps the platform-specific ID to a unified user

Session manager loads the correct session (based on strategy)

Hermes Core processes the message with full context

Response formatter adapts the response for the target platform

Adapter sends the formatted response back

Platform-Specific Formatting

Each platform has different formatting capabilities. The gateway automatically adapts:

Hermes response (internal):
  "Here's a Python function:\n

python\ndef hello():\n print('Hi')\n``

"

→ Telegram: Markdown with monospace code block
→ Discord: Discord-flavored markdown with syntax highlighting

→ Slack: Slack mrkdwn with `preformatted` blocks


→ WhatsApp: Plain text with indented code (no syntax highlighting)

Smart Model Routing

The gateway can automatically choose the best model based on the message content:

yaml
gateway:
  smart_routing:
    enabled: true
    rules:
      - pattern: "review|debug|fix|refactor"
        model: "anthropic/claude-3.5-sonnet"
        reason: "Code tasks need a strong model"

      - pattern: "translate|summarize|explain"
        model: "openai/gpt-4o-mini"
        reason: "Simple tasks, save costs"

      - pattern: "image|picture|photo|screenshot"
        model: "openai/gpt-4o"
        reason: "Multimodal capability needed"

      - default:
        model: "openai/gpt-4o-mini"

Cross-Platform Features

Unified Memory

With identity mapping, a user's memories persist across all platforms:


[Telegram] You: /memory save I prefer Python over JavaScript
✅ Saved to long-term memory

[Discord] You: /ask Write me a web scraper
Hermes: Based on your preference, here's a Python web scraper...
# (Remembers the preference saved on Telegram!)

Cross-Platform Notifications

Send alerts or cron results to any platform:

yaml
cron:
  tasks:
    - name: "Daily server health check"
      schedule: "0 9   *"
      command: "Check server status and report issues"
      notify:
        telegram: [123456789]                    # Send to my phone
        slack: ["C01234ABCDE"]                   # Post to #ops channel
        discord: ["1234567890123456789"]          # Post to #alerts

Message Forwarding

Forward conversations between platforms:


[Slack] Alice: @Hermes summarize the Q4 planning thread

[Hermes Response in Slack]
Summary: The team agreed on 3 priorities...

# If forwarding is enabled, this can also appear in:
[Discord #planning-updates] Hermes: [From Slack #general]
Summary from Alice's request: The team agreed on...

Production Deployment

Docker Compose

yaml
# docker-compose.yml
version: '3.8'
services:
  hermes-gateway:
    image: hermes-agent:latest
    command: gateway start
    restart: always
    environment:
      - HERMES_API_KEY=sk-or-v1-your-key
      - HERMES_TELEGRAM_TOKEN=7123456789:AAH...
      - HERMES_DISCORD_TOKEN=MTIzNDU2Nzg5MDEy...
      - HERMES_SLACK_TOKEN=xoxb-...
    volumes:
      - hermes-data:/root/.hermes
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  hermes-data:

bash
docker compose up -d

Monitoring

The gateway exposes a health and metrics endpoint:

bash
# Health check
curl http://localhost:8080/health

# Metrics
curl http://localhost:8080/metrics

json
{
  "status": "healthy",
  "uptime": "48h 23m",
  "adapters": {
    "telegram": { "status": "connected", "messages_today": 142 },
    "discord": { "status": "connected", "messages_today": 89 },
    "slack": { "status": "connected", "messages_today": 203 }
  },
  "ai_usage": {
    "tokens_today": 450000,
    "cost_today": "$1.23",
    "avg_response_time": "2.1s"
  }
}

Error Handling and Resilience

The gateway handles adapter failures gracefully:

yaml
gateway:
  resilience:
    # Retry failed messages
    max_retries: 3
    retry_delay: 5000       # ms

    # Circuit breaker
    circuit_breaker:
      enabled: true
      failure_threshold: 5  # Consecutive failures before opening
      reset_timeout: 60000  # ms before attempting reconnect

    # Fallback behavior
    fallback:
      # If one adapter fails, notify through others
      notify_other_platforms: true
      message: "⚠️ {platform} adapter is temporarily down. I'm still available on other platforms."

Scaling Considerations

Single Instance (1-10 users)

The default setup handles small teams easily:

bash
hermes gateway start

Medium Scale (10-100 users)

Use PM2 cluster mode:

bash
pm2 start "hermes gateway start" --name hermes-gw -i 2

Large Scale (100+ users)

For large deployments, separate adapters from the core:


[Telegram Adapter] ──→ [Redis Queue] ──→ [Hermes Worker Pool]
[Discord Adapter]  ──→ [Redis Queue] ──→ [Hermes Worker Pool]
[Slack Adapter]    ──→ [Redis Queue] ──→ [Hermes Worker Pool]

yaml
gateway:
  queue:
    enabled: true
    backend: "redis"
    redis_url: "redis://localhost:6379"
    workers: 4

Security Architecture


Internet
    │
    ▼
[Firewall / Cloudflare]
    │
    ▼
[SSL Termination (nginx)]
    │
    ▼
[Rate Limiter]
    │
    ▼
[Auth Layer]           ← Validates platform tokens, user ACL
    │
    ▼
[Hermes Gateway]       ← Sandboxed file system access
    │
    ▼
[AI Model Provider]    ← API key encrypted at rest

Key security measures:

[ ] All platform tokens encrypted at rest
[ ] Per-user rate limiting across platforms
[ ] File system sandboxing
[ ] Audit logging for all interactions
[ ] Regular credential rotation

Next Steps

Telegram setup — Start with one platform
Multi-agent orchestration — Run multiple agents through the gateway
Server monitoring — Get alerts via the gateway

Last updated: April 16, 2026 · Hermes Agent v0.8

← Back to TutorialsTutorial Index