Hermes Agent messaging gateway explained

One background process for messaging and automation

The gateway is a long-running Hermes process that connects your agent to chat apps and other inbound routes. It handles incoming messages, keeps conversation sessions, runs scheduled jobs and delivers replies. Media support depends on the adapter and speech configuration. If you only use Hermes interactively in the terminal, you do not need the gateway. Agent-driven scheduled jobs need a running gateway even when output stays local. Script-only (no_agent) jobs run by hermes cron tick are the documented exception.

Compare the chat apps and other documented routes at messaging platforms. They have different media support, account requirements and access controls.

• Use the hub's grouped directory for personal, team, iMessage, self-hosted and regional apps, notifications, browser clients and Hermes's own apps.
• The WhatsApp Business Cloud API guide explains its public callback, direct-chat support and 24-hour reply window.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

Start in the foreground and send one harmless message from an allowed account before installing a service. Keep credentials in the active profile's .env and out of Git, screenshots and chat transcripts. A saved token does not prove that incoming messages or replies reach the right conversation.

A service can keep running after a terminal closes. See How to run Hermes Agent 24/7 on a VPS or home server for hosting choices.

• hermes gateway setup: an interactive wizard for configuring platforms and their tokens.
• hermes gateway: run in the foreground, useful for a first test where you can watch the output.
• hermes gateway install: install it as a user service (systemd on Linux, launchd on macOS, a Scheduled Task called Hermes_Gateway on Windows). sudo hermes gateway install --system creates a boot-time service on Linux.
• hermes gateway start, hermes gateway stop, hermes gateway status: manage the installed service.
• hermes gateway restart: prefer this over a raw systemctl restart, because it lets replies in progress finish first.

Who is allowed to talk to your bot

Human messages need an explicit execution grant. Supported grants include platform allow-all, operator-approved pairing, user/group/chat allowlists, Discord roles and supported local policy grants. An allowlist lists who may use the agent. A terminal-capable bot exposes the host's tools, so keep allow-all disabled on a private bot. GATEWAY_ALLOW_ALL_USERS is a fallback only when no relevant allowlists are set, rather than an unconditional final override. Authenticated webhooks, service events and Relay ingress use separate trust boundaries.

Unknown chat DMs can use operator-approved pairing. When a code is issued, approve it on the host with hermes pairing approve <platform> <code>. Codes expire after one hour, pending requests are capped at three per platform, and five failed approval attempts cause a one-hour lockout. Explicit allowlists and restrictive policies can suppress new prompts. Email ignores unknown senders by default; pairing is opt-in and still requires an authenticated From header. hermes pairing list shows pairing state. To remove access, revoke the pairing with hermes pairing revoke <platform> <user-id> and remove other grants such as an allowlist entry.

You can also split admins from regular users so that only admins run sensitive slash commands, using allow_admin_from and user_allowed_commands.

How conversations behave

Chat sessions persist until someone sends /new or /reset; they no longer reset on inactivity or at a fixed time, and compression keeps long threads manageable. In groups, each user gets a separate session by default. If the gateway crashes after producing a reply, its delivery ledger in state.db supports up to three resend attempts within 24 hours. This covers outgoing replies only. Incoming messages are separate; check your platform's documented backlog behavior. Inspect the destination and ledger when delivery is uncertain; recovery does not establish that a recipient received a reply.

If you send a message while Hermes is busy, the default is to redirect the current turn. display.busy_input_mode can switch that to queue (run it next) or steer (inject it after the next tool call). For long jobs, /bg <prompt> runs the task in a separate session and posts the result back to the same chat when it finishes, so your main conversation stays free.

One gateway can serve several profiles in one host process when its safety checks permit it. Use hermes -p <name> gateway setup for profile-scoped credentials, then inspect hermes gateway status and the served profile set. Starting a named profile can attach to the existing host instead of creating another process. Read the multi-profile gateway docs before installing another service; older separate-process recipes are not the current default.

Useful in-chat commands

• /status shows session info; /whoami shows your slash-command access tier (admin, user or unrestricted) in this chat.
• /model: switch model; choices survive restarts, --global writes the change to config and --once applies it to a single turn.
• /stop, /retry and /undo: cancel, re-run or roll back the last turn.
• /approve and /deny: answer approval prompts from your phone.
• /sethome chooses the home destination on supported chats. Chat-created jobs default to deliver=origin; CLI-created jobs default to local output. A bare platform target uses its home channel, while an explicit chat/topic target selects that destination. See Hermes Agent task finished but no message arrived.
• /platform list|pause|resume: manage individual platform adapters.

Where to look when something is off

Gateway logs are in the active profile's ~/.hermes/logs/gateway.log; Linux users can also follow journalctl --user -u hermes-gateway -f. A stalled event loop can exit with code 75 for a supervisor to recover. On Windows, Task Scheduler watches a short-lived launcher, not the long-running gateway, so an externally killed or crashed gateway may stay down until hermes gateway start. Check actual runtime and platform state. If a platform keeps failing, Hermes pauses it (a circuit breaker). Investigate the failures, then /platform resume <name>.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes messaging gateway docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived
• Hermes Agent profiles: separate agents for separate jobs
• Hermes Agent security: approvals, allowlists, sandboxing
• How to set up Hermes Agent on Telegram
• How to set up Hermes Agent on Discord
• How to set up Hermes Agent on WhatsApp with the Baileys bridge
• How to set up Hermes Agent on WhatsApp with the Business Cloud API
• How to set up Hermes Agent with Open WebUI and the API server

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher