Hermes Agent

Integration

Hermes Agent Discord Setup: Bot, Permissions & Threads

Set up Hermes Agent on Discord with bot intents, fail-closed access, thread sessions, Gateway WebSocket checks, duplicate-reply diagnosis, and an exact-channel reply test.

Quick answer

Create a Discord application and bot, enable Server Members Intent and Message Content Intent, invite it with bot plus applications.commands, then run hermes gateway setup under the profile that will stay online. Configure at least one allowed user, role, or channel because Hermes fails closed without an access policy. Prove one real reply in the exact DM, channel, thread, or forum post. A grey badge with working replies is not by itself an outage. If startup rejects privileged intents, fix those before testing authorization. If Discord connects but the bot is silent, check inbound Gateway events, allowlist and mention decisions, then provider completion and outbound delivery—in that order. If one message gets two replies, look for two gateway processes before changing prompts or model settings.

Bot, intents, access policy, and reply test · Connected channels without gateway upkeep

Best for

Team support channels and community triage where replies should stay visible to the group

Slash-command workflows with permission boundaries instead of a broad always-listening bot

Threaded debugging and human-agent handoffs in Discord forum channels

Cron, GitHub, CI, Kanban, and gateway alerts delivered to a shared operations room

Teams comparing a self-hosted bot stack against FlyHermes managed cloud channels

Features

  • ✓Discord bot setup through the Developer Portal with narrow bot scopes and channel permissions
  • ✓Slash commands, app mentions, free-response channels, and thread-aware team workflows
  • ✓Server Members Intent and Message Content Intent enabled for the Hermes Discord adapter, including mention-only workflows
  • ✓Fail-closed user, role, or channel authorization before inbound messages reach the agent
  • ✓Per-user shared-channel sessions so teammates do not inherit one another's context by default
  • ✓Thread and forum-post isolation with configurable mention rules for multi-bot rooms
  • ✓Gateway WebSocket health checks using ready state, socket openness, heartbeat ACK age, latency, logs, and Web UI
  • ✓Safe slash-command synchronization that updates only changed commands instead of bulk-registering every startup
  • ✓Dedicated Hermes profiles so community bots receive only the intended secrets, memory, skills, and tools
  • ✓A five-check Discord incident ladder: one inbound event, one authorization decision, one agent turn, one outbound send, and exactly one reply

Setup path

  1. 1Create a Discord application and bot in the Discord Developer Portal.
  2. 2Enable Server Members Intent and Message Content Intent in the Developer Portal. Hermes requests message content even when you only plan to use mentions; channel permissions and mention rules still limit where it responds.
  3. 3Invite the bot to one test server and one private channel before expanding to public channels or forum threads.
  4. 4Put the bot token in the active Hermes gateway profile and avoid committing tokens into Docker Compose files or screenshots.
  5. 5Run hermes gateway setup, select Discord, and configure at least one allowed user, role, or channel so the integration does not fail closed.
  6. 6Reload the gateway configuration, then verify end to end with hermes gateway status, Web UI platform status, one Discord mention or slash command, and recent agent logs.
  7. 7For a 24/7 bot, verify Gateway WebSocket heartbeat health and keep DISCORD_COMMAND_SYNC_POLICY=safe unless you deliberately need bulk or disabled command sync.
  8. 8Only after the test channel works, add support threads, cron alerts, GitHub/CI notifications, or community moderation workflows.

Grey badge, connection rejection or denied message?

Do not restart a working bot just to change its badge. Use the Discord setup diagnosis to choose the first failing layer, then verify one reply in the actual destination.

  • •Grey badge but replies work: preserve the token; confirm the bot identity and test the intended server channel or thread separately from DMs.
  • •Startup reports PrivilegedIntentsRequired: enable the requested intents in the Developer Portal and save. Hermes always requests Message Content Intent; username or role allowlists also request Server Members Intent. Presence Intent is not required for message handling.
  • •Connected but logs say No Discord access policy configured: set an explicit allowed user, role or channel in the owning profile, rather than opening access to everyone.
  • •Read the official Discord troubleshooting reference. Connection, authorization and a completed reply are separate checks.

How Hermes behaves in Discord

Hermes uses the full messaging gateway rather than a stateless webhook. Authorization, mention rules, session lookup, memory, tools, model execution, and response delivery all happen before a reply appears.

  • •Direct messages respond without an @mention and keep their own sessions.
  • •Server channels require an @mention by default; selected free-response channels can answer inline.
  • •Threads keep their own session namespace and reply inside the same thread.
  • •Shared channels isolate history per user by default through group_sessions_per_user: true.

Fail-closed access before powerful tools

A Discord bot can appear online while Hermes rejects every inbound message. Configure an allowed user, role, or channel before debugging the model. For a team or community bot, pair that policy with a dedicated Hermes profile and a deliberately small toolset.

  • •Use allowed users for a private personal bot.
  • •Use allowed roles for a changing moderator or support team.
  • •Use allowed channels to keep a server bot out of unrelated rooms.
  • •Keep tokens in the active profile environment—not prompts, screenshots, or Compose files.

Mention rules, free-response rooms, and threads

Start mention-only so Hermes does not jump into ordinary conversations. Make only dedicated bot rooms free-response, and require mentions inside multi-bot threads when several agents share the same discussion.

  • •Use DISCORD_FREE_RESPONSE_CHANNELS for dedicated mention-free bot rooms.
  • •Keep global mention gating enabled in mixed human channels.
  • •Use discord.thread_require_mention: true when multiple bots share a thread.
  • •Use history backfill only when mention-gated context should include recent channel messages.

The four-layer Discord proof

Do not rotate a valid bot token because the model is out of credits or a thread lacks permission. Prove each layer separately, then test the exact production surface.

  • •Provider: one CLI response from the same Hermes profile.
  • •Gateway: connected Discord state plus an inbound event in recent logs.
  • •Permission: one mention or slash command in a private channel.
  • •Production: one reply in the exact thread, forum post, or room the team will use.

Self-hosted Discord or managed FlyHermes?

Self-hosting gives you control over profiles, tools, secrets, logs, and deployment. It also makes your team responsible for keeping the gateway, provider route, server, updates, and delivery monitoring healthy. FlyHermes is the managed route when browser, mobile, and connected-channel access matter more than owning that operations stack.

  • •Self-host when local system access and infrastructure control are the goal.
  • •Use managed cloud when channel uptime and remote access are business requirements.
  • •Self-hosted WebUI includes browser Chat through PTY/WebSocket as well as monitoring. FlyHermes changes who maintains the runtime, not whether browser chat exists.

Fix duplicate replies and silent channels without guessing

A September 2026 community report described duplicate Discord replies. Treat duplicates and silence as transport evidence, not prompt quality. Use one timestamped test message and trace it across the event, policy, agent, and delivery layers.

  • •No inbound event: inspect Gateway WebSocket health, privileged intents, channel visibility, thread membership, and mention rules.
  • •Inbound event but no agent turn: inspect allowed users, roles, channels, and the active profile before changing the model.
  • •Agent turn fails: inspect provider authentication, credits, rate limits, and context errors with the provider-cost runbook.
  • •Outbound send fails: inspect Discord send permissions and thread state in the exact target, not only a test channel.
  • •Two replies: prove whether two gateway processes, containers, profiles, or hosts are consuming the same bot events.

Heartbeat ACKs can pass while messages stop arriving

A green bot badge and successful REST lookup are not a reply test. Current Hermes also checks the age of the last parsed Gateway event. A connection can keep acknowledging heartbeats while delivering no events to the adapter. Use the official Discord WebSocket-health documentation for the settings supported by your installed version.

  • •The documented event-silence default is 14400 seconds (four hours). A quiet server can legitimately be silent, so do not shorten it just to make the status look responsive.
  • •discord.websocket_event_max_silence_seconds: 0 disables only the event-silence check. Other liveness knobs set to zero disable the whole probe; invalid values also disable it and produce startup warnings.
  • •A confirmed closed socket or client triggers reconnect on the first unhealthy sample. The consecutive-failure threshold applies to soft signals such as stale ACKs, latency or event silence.
  • •After recovery, send one harmless mention in the actual channel and verify a reply there. Then test the production thread separately. Do not add another reconnect loop.

Check the service profile before changing credentials

If your CLI answers but the Discord service does not, compare the profile and runtime account first. Run hermes config path and hermes config env-path in the environment that starts the gateway; use the same -p profile selection as the service. These commands show paths without printing credentials.

  • •A Windows gateway-locks PermissionError is a filesystem failure. Discord Administrator cannot repair it; inspect the exact path and runtime account instead of deleting a lock.
  • •No Discord adapter startup entry is different from a connected adapter that receives no events. Check the deployed environment and first startup error before changing mention rules.
  • •Keep the token private. Managed hosting can remove service maintenance, but Discord permissions and model-provider access still need to be correct.

Why an online Discord bot can still be silent

Discord connectivity is only one checkpoint. Hermes still applies authorization, mention rules, session routing, provider execution, and response delivery. The fastest diagnosis is therefore access policy → inbound log event → provider smoke test → exact channel or thread permission—not repeated token regeneration.

Session isolation is a team-safety control

Per-user channel sessions prevent one teammate's context, token growth, in-flight task, or reset from becoming everyone else's by default. Shared sessions are useful for a truly collaborative room, but they should be an explicit choice rather than an accidental side effect of putting several people in one channel.

Common setup issues

  • Bot connected but not responding: check the fail-closed user/role/channel policy, mention rules and channel permissions. PrivilegedIntentsRequired is a separate startup rejection, not proof that a connected bot needs a new token.
  • Works locally but fails in Docker/VPS: verify the container or service has the same Discord token, profile path, .env values, and working directory as your local smoke test.
  • Thread or forum replies fail: test one normal channel first, then the exact thread or forum post; check bot membership, inherited permissions, and thread mention policy.
  • Unauthorized users trigger reactions or threads: narrow role/channel permissions and split the Discord bot into a dedicated Hermes profile with fewer tools.
  • Messages reach Hermes but no reply is posted: smoke-test the model from the same profile, then inspect provider credits, rate limits, context errors, and recent agent logs.
  • Two people share or interrupt one another's context: keep group_sessions_per_user: true; use a shared room session only when the team deliberately wants one transcript and running-agent slot.
  • Dashboard says connected but Discord is silent: use Web UI as a checkpoint, then send one real message in the target surface before rotating a working token.
  • Duplicate replies: check for two gateway processes or bot instances consuming the same Discord events.
  • Bot is online and Discord REST checks pass, but new messages never arrive: inspect Gateway WebSocket ready/socket state, heartbeat ACK age, and latency. Hermes reconnects after repeated unhealthy samples; do not add a second custom reconnect loop.
  • One message produces two replies: capture both reply timestamps, stop the extra gateway/container/host, verify only one process owns the bot token, then repeat one controlled message. Prompt changes do not fix duplicate event consumers.
  • Bot appears online but logs show no inbound event: stay on Discord Gateway health, intents, channel visibility, thread membership, and mention gating. Do not rotate provider credentials until the event reaches Hermes.

Keep building the workflow

FAQ

How do I add Hermes Agent to Discord?

Create a Discord app and bot, invite it with narrow scopes, configure the token and an allowed user, role, or channel through Hermes gateway setup, reload the gateway configuration, then verify one mention or slash command in a private test channel.

Why is my Hermes Discord bot online but not responding?

Check current connection logs rather than trusting badge colour. A connected bot can deny users because no access policy is configured. After authorization, inspect mention rules, channel permissions, the active profile and the provider turn. A privileged-intent startup rejection is a separate failure.

Does Hermes Agent need Discord administrator permissions?

Usually no. Start with the smallest permission set that lets the bot view one test channel, receive the intended command or mention, and post a reply. Expand only when a proven workflow requires it.

Can Hermes Agent run in Discord threads and forum channels?

Yes. Threads use their own session namespace and replies stay in the thread. Test a normal channel first, then the exact private thread or forum post because membership, inherited permissions, and mention rules can differ.

Do teammates share one Hermes conversation in Discord?

Not by default. With group_sessions_per_user: true, each user in a shared channel has separate history and a separate running-agent slot. Disable it only when the room intentionally needs one shared transcript.

Should I self-host the Discord bot or use FlyHermes?

Self-host when you want full control over profiles, tools, tokens, server processes, and logs. Use FlyHermes when your priority is managed browser, mobile, and connected-channel access without operating the gateway stack yourself.

Why can the Discord REST API work while Hermes receives no messages?

Discord REST and the Gateway WebSocket are separate transports. A successful user lookup or bot-online state does not prove the event socket is open or receiving heartbeat acknowledgements. Check Hermes gateway logs and WebSocket health before rotating a valid token.

Why does my Hermes Discord bot reply twice to one message?

The most common cause is two active gateway processes or deployments consuming events for the same bot token. Stop the extra process, verify one owning profile and host, then repeat one timestamped message. Prompt or model changes will not remove a duplicate event consumer.

Can Discord heartbeat checks pass while Hermes receives no events?

Yes. Current Hermes also checks elapsed time since the last parsed Gateway event. The documented default is four hours; a quiet server may be legitimately silent. Setting websocket_event_max_silence_seconds to zero disables only that dimension. Verify recovery with a real reply in the target channel.

Does Presence Intent make my Hermes bot show as online?

It is not the switch for your own bot badge and is not required for Hermes message handling. A grey badge with working replies should be investigated separately from a rejected connection or a failed channel reply.

Related setup guides

Other Integrations