본문으로 건너뛰기

Messaging Gateway

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, 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​

PlatformVoiceImagesFilesThreadsReactionsTypingStreaming
Telegram✅✅✅✅—✅✅
Discord✅✅✅✅✅✅✅
Slack✅✅✅✅✅✅✅
Google Chat—✅✅✅—✅—
WhatsApp—✅✅——✅✅
Signal—✅✅——✅✅
SMS———————
Email—✅✅✅———
Home Assistant———————
Mattermost✅✅✅✅—✅✅
Matrix✅✅✅✅✅✅✅
DingTalk—✅✅—✅—✅
Feishu/Lark✅✅✅✅✅✅✅
WeCom✅✅✅——✅✅
WeCom Callback———————
Weixin✅✅✅——✅✅
BlueBubbles—✅✅—✅✅—
QQ✅✅✅——✅—
Yuanbao✅✅✅——✅✅
Microsoft Teams—✅—✅—✅—
LINE—✅✅——✅—

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)​

CommandDescription
/new or /resetStart a fresh conversation
/model [provider:model]Show or change the model (supports provider:model syntax)
/personality [name]Set a personality
/retryRetry the last message
/undoRemove the last exchange
/statusShow session info
/whoamiShow your slash command access on this scope (admin / user / unrestricted)
/stopStop the running agent
/approveApprove a pending dangerous command
/denyReject a pending dangerous command
/sethomeSet this chat as the home channel
/compressManually compress conversation context
/title [name]Set or show the session title
/resume [name]Resume a previously named session
/usageShow token usage for this session
/insights [days]Show usage insights and analytics
/reasoning [level|show|hide]Change reasoning effort or toggle reasoning display
/voice [on|off|tts|join|leave|status]Control messaging voice replies and Discord voice-channel behavior
/rollback [number]List or restore filesystem checkpoints
/background <prompt>Run a prompt in a separate background session
/reload-mcpReload MCP servers from config
/updateUpdate Hermes Agent to the latest version
/helpShow available commands
/<skill-name>Invoke any installed skill

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:

PolicyDefaultDescription
Daily4:00 AMReset at a specific hour each day
Idle1440 minReset after N minutes of inactivity
Both(combined)Whichever triggers first

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
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

# 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.

Admins vs Regular Users​

Allowlists answer "can this person reach the bot at all?" The admin / user split answers "now that they're in, what are they allowed to do?"

Every allowed user falls into one of two tiers per scope (DM vs group/channel):

  • Admin — full access. Can run every registered slash command (built-in + plugin) and use every gated capability.
  • Regular user — restricted access. Can chat with the agent normally, but can only run the slash commands you explicitly enable. The always-allowed floor is /help and /whoami.

The tiers are configured per platform and per scope. DM admin status does not imply group/channel admin status — each scope has its own admin list.

What the tiers gate today: slash commands. The split runs through the live command registry, so it covers built-ins and plugin-registered commands without per-feature wiring. Plain chat is not affected — non-admins can still talk to the agent.

What may be gated in the future: more capability surfaces (tool access, model switching, expensive operations) will hang off the same admin / user distinction as we add them. Configuring the split now means those future restrictions land cleanly without you having to re-model who's an admin.

Configuration​

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # admins → all slash commands
        user_allowed_commands: [status, model]       # what non-admins may run
        # Optional: separate group/channel scope
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

Backward compat: if allow_admin_from is not set for a scope, the tier split is disabled for that scope and every allowed user has full access. Existing installs keep working with no changes — opt in when you want the distinction.

Inspecting your access​

Use /whoami from any platform to see the active scope, your tier (admin / user / unrestricted), and which slash commands you can run. See the Telegram and Discord pages for platform-specific examples.

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

Queue vs interrupt vs steer (busy-input mode)​

By default, messaging a busy agent interrupts it. Two other modes are available:

  • queue — follow-up messages wait and run as the next turn after the current task finishes.
  • steer — follow-up messages are injected into the current run via /steer, arriving at the agent after the next tool call. No interrupt, no new turn. Falls back to queue behavior if the agent hasn't started yet.
display:
  busy_input_mode: steer   # or queue, or interrupt (default)
  busy_ack_enabled: true   # set to false to suppress the ⚡/⏳/⏩ chat reply entirely

The first time you message a busy agent on any platform, Hermes appends a one-line reminder to the busy-ack explaining the knob ("💡 First-time tip — …"). The reminder fires once per install — a flag under onboarding.seen.busy_input_prompt latches it. Delete that key to see the tip again.

If you find the busy-ack noisy — especially with voice input or rapid-fire messages — set display.busy_ack_enabled: false. Your input is still queued/steered/interrupts as normal, only the chat reply is silenced.

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
ModeWhat you receive
allRunning-output updates and the final completion message (default)
resultOnly the final completion message (regardless of exit code)
errorOnly the final message when the exit code is non-zero
offNo process watcher messages at all

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"
팁

Background tasks on messaging platforms are fire-and-forget — you don't need to wait or check on them. Results arrive in the same chat automatically when the task finishes.

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.

Multiple installations

If you run multiple Hermes installations on the same machine (with different HERMES_HOME directories), each gets its own systemd service name. The default ~/.hermes uses hermes-gateway; other installations use hermes-gateway-<hash>. The hermes gateway commands automatically target the correct service for your current HERMES_HOME.

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.
PATH changes after install

launchd plists are static — if you install new tools (e.g. a new Node.js version via nvm, or ffmpeg via Homebrew) after setting up the gateway, run hermes gateway install again to capture the updated PATH. The gateway will detect the stale plist and reload automatically.

Multiple installations

Like the Linux systemd service, each HERMES_HOME directory gets its own launchd label. The default ~/.hermes uses ai.hermes.gateway; other installations use ai.hermes.gateway-<suffix>.

Platform-Specific Toolsets​

Each platform has its own toolset:

PlatformToolsetCapabilities
CLIhermes-cliFull access
Telegramhermes-telegramFull tools including terminal
Discordhermes-discordFull tools including terminal
WhatsApphermes-whatsappFull tools including terminal
Slackhermes-slackFull tools including terminal
Google Chathermes-google_chatFull tools including terminal
Signalhermes-signalFull tools including terminal
SMShermes-smsFull tools including terminal
Emailhermes-emailFull tools including terminal
Home Assistanthermes-homeassistantFull tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services)
Mattermosthermes-mattermostFull tools including terminal
Matrixhermes-matrixFull tools including terminal
DingTalkhermes-dingtalkFull tools including terminal
Feishu/Larkhermes-feishuFull tools including terminal
WeComhermes-wecomFull tools including terminal
WeCom Callbackhermes-wecom-callbackFull tools including terminal
Weixinhermes-weixinFull tools including terminal
BlueBubbleshermes-bluebubblesFull tools including terminal
QQBothermes-qqbotFull tools including terminal
Yuanbaohermes-yuanbaoFull tools including terminal
Microsoft Teamshermes-teamsFull tools including terminal
API Serverhermes-api-serverFull tools (drops clarify, send_message, text_to_speech — programmatic access doesn't have an interactive user)
Webhookshermes-webhookFull tools including terminal

Operating a multi-platform gateway​

A gateway typically runs several adapters at once (Telegram + Discord + Slack, etc.). The sections below cover day-2 operations that span all platforms.

/platform command​

Once the gateway is running, use the /platform slash command from any connected CLI session or chat to inspect and steer individual adapters without restarting the whole gateway:

/platform list                  # show all adapters and their state
/platform pause <name>          # stop dispatching new messages to one adapter
/platform resume <name>         # re-enable a paused adapter

/platform list shows whether each adapter is running, paused (manually), or paused-by-breaker (see below). Pausing keeps the adapter loaded and its background loops alive — incoming messages are dropped on the floor, but the connection itself stays open so resume is instant.

See also the broader status summary command /platforms.

Automatic circuit breaker​

Each adapter is wrapped in a circuit breaker. Repeated retryable failures (network blips, rate-limit replies, 5xx upstream responses, websocket disconnects) cause the breaker to trip — the adapter is auto-paused, an operator notification is sent to the home channel of another live platform when one is configured, and a structured log line is emitted.

The breaker does not auto-resume — it stays open until you run /platform resume <name> manually. This is intentional: if a platform is in a sustained outage, you don't want the gateway thrashing reconnects.

Where to look when a platform is paused​

When an adapter is paused, check:

  1. Gateway log (~/.hermes/logs/gateway.log or the systemd / launchd unit log). Search for the platform name and circuit breaker, paused, or disabled. The trip event includes the failure count and the last error.
  2. /platform list output — shows the current state and last reason.
  3. The provider's status page (Telegram bot API status, Discord status, etc.). The breaker tripped because the platform was unhealthy; don't try to resume until it's back.

Once upstream is healthy, /platform resume <name> clears the breaker and re-arms the adapter.

Restart notifications​

When the gateway restarts (or is shut down with in-flight sessions), it can send a one-shot "the agent is back" / "the agent was interrupted" message to each platform's home channel. This is controlled per-platform by the gateway_restart_notification flag in gateway-config.yaml, which defaults to true:

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # opt out for this platform
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification omitted → defaults to true

Disable it on noisy or low-priority platforms while leaving it on for your primary chat. The notification is sent once per restart, regardless of how many sessions were in flight.

Session resume across gateway restarts​

When the gateway shuts down with an in-flight tool call or generation, the affected sessions are flagged as restart_interrupted. On the next startup, the gateway schedules an auto-resume for each one — the user gets a short heads-up in the chat ("Send any message after restart and I'll try to resume where you left off.") and the session picks up from the last committed turn when they reply.

This behaviour is on by default and is logged at gateway start:

Scheduled auto-resume for N restart-interrupted session(s)

No configuration is required. If you don't want the heads-up, set gateway_restart_notification: false on the platform.

Progress bubble cleanup (opt-in)​

Tool-progress messages, the "still working…" heartbeat, and status-callback bubbles can be auto-deleted after the final response lands. Enable per-platform via display.platforms.<platform>.cleanup_progress:

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

Defaults to false. Only platforms whose adapter implements delete_message honor the setting (currently Telegram and Discord). Failed runs skip cleanup so the bubbles remain as breadcrumbs.

Next Steps​