Messaging Gateway

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see Voice Mode and Use Voice Mode with Hermes.

Platform Comparison​

Voice = TTS audio replies and/or voice message transcription. Images = send/receive images. Files = send/receive file attachments. Threads = threaded conversations. Reactions = emoji reactions on messages. Typing = typing indicator while processing. Streaming = progressive message updates via editing.

Architecture​

Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs.

Quick Setup​

The easiest way to configure messaging platforms is the interactive wizard:

hermes gateway setup        # Interactive setup for all messaging platforms

This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway when done.

Gateway Commands​

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Chat Commands (Inside Messaging)​

Session Management​

Session Persistence​

Sessions persist across messages until they reset. The agent remembers your conversation context.

Reset Policies​

Sessions reset based on configurable policies:

Configure per-platform overrides in ~/.hermes/gateway.json:

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

Security​

By default, the gateway denies all users who are not in an allowlist or paired via DM. This is the safe default for a bot with terminal access.

# Restrict to specific users (recommended):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1

# Or allow
GATEWAY_ALLOWED_USERS=123456789,987654321

# Or explicitly allow all users (NOT recommended for bots with terminal access):
GATEWAY_ALLOW_ALL_USERS=true

DM Pairing (Alternative to Allowlists)​

Instead of manually configuring user IDs, unknown users receive a one-time pairing code when they DM the bot:

# The user sees: "Pairing code: XKGH5N7P"
# You approve them with:
hermes pairing approve telegram XKGH5N7P

# Other pairing commands:
hermes pairing list          # View pending + approved users
hermes pairing revoke telegram 123456789  # Remove access

Pairing codes expire after 1 hour, are rate-limited, and use cryptographic randomness.

Interrupting the Agent​

Send any message while the agent is working to interrupt it. Key behaviors:

• In-progress terminal commands are killed immediately (SIGTERM, then SIGKILL after 1s)
• Tool calls are cancelled — only the currently-executing one runs, the rest are skipped
• Multiple messages are combined — messages sent during interruption are joined into one prompt
• /stop command — interrupts without queuing a follow-up message

Tool Progress Notifications​

Control how much tool activity is displayed in ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # set to true to enable /verbose in messaging

When enabled, the bot sends status messages as it works:

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

Background Sessions​

Run a prompt in a separate background session so the agent works on it independently while your main chat stays responsive:

/background Check all servers in the cluster and report any that are down

Hermes confirms immediately:

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

How It Works​

Each /background prompt spawns a separate agent instance that runs asynchronously:

• Isolated session — the background agent has its own session with its own conversation history. It has no knowledge of your current chat context and receives only the prompt you provide.
• Same configuration — inherits your model, provider, toolsets, reasoning settings, and provider routing from the current gateway setup.
• Non-blocking — your main chat stays fully interactive. Send messages, run other commands, or start more background tasks while it works.
• Result delivery — when the task finishes, the result is sent back to the same chat or channel where you issued the command, prefixed with "✅ Background task complete". If it fails, you'll see "❌ Background task failed" with the error.

Background Process Notifications​

When the agent running a background session uses terminal(background=true) to start long-running processes (servers, builds, etc.), the gateway can push status updates to your chat. Control this with display.background_process_notifications in ~/.hermes/config.yaml:

display:
  background_process_notifications: all    # all | result | error | off

You can also set this via environment variable:

HERMES_BACKGROUND_NOTIFICATIONS=result

Use Cases​

• Server monitoring — "/background Check the health of all services and alert me if anything is down"
• Long builds — "/background Build and deploy the staging environment" while you continue chatting
• Research tasks — "/background Research competitor pricing and summarize in a table"
• File operations — "/background Organize the photos in ~/Downloads by date into folders"

Service Management​

Linux (systemd)​

hermes gateway install               # Install as user service
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
journalctl --user -u hermes-gateway -f  # View logs

# Enable lingering (keeps running after logout)
sudo loginctl enable-linger $USER

# Or install a boot-time system service that still runs as your user
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger.

Avoid keeping both the user and system gateway units installed at once unless you really mean to. Hermes will warn if it detects both because start/stop/status behavior gets ambiguous.

macOS (launchd)​

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

The generated plist lives at ~/Library/LaunchAgents/ai.hermes.gateway.plist. It includes three environment variables:

• PATH — your full shell PATH at install time, with the venv bin/ and node_modules/.bin prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge.
• VIRTUAL_ENV — points to the Python virtualenv so tools can resolve packages correctly.
• HERMES_HOME — scopes the gateway to your Hermes installation.

Platform-Specific Toolsets​

Each platform has its own toolset:

Next Steps​

• Telegram Setup
• Discord Setup
• Slack Setup
• WhatsApp Setup
• Signal Setup
• SMS Setup (Twilio)
• Email Setup
• Home Assistant Integration
• Mattermost Setup
• Matrix Setup
• DingTalk Setup
• Feishu/Lark Setup
• WeCom Setup
• Open WebUI + API Server
• Webhooks