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, 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. If the bot is online but 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
- ✓Message Content Intent guidance so the bot reads messages only when the workflow needs it
- ✓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
- 1Create a Discord application and bot in the Discord Developer Portal.
- 2Choose the smallest permission surface: slash commands/app mentions first, Message Content Intent only when ordinary channel text is needed.
- 3Invite the bot to one test server and one private channel before expanding to public channels or forum threads.
- 4Put the bot token in the active Hermes gateway profile and avoid committing tokens into Docker Compose files or screenshots.
- 5Run
hermes gateway setup, select Discord, and configure at least one allowed user, role, or channel so the integration does not fail closed. - 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. - 7For a 24/7 bot, verify Gateway WebSocket heartbeat health and keep
DISCORD_COMMAND_SYNC_POLICY=safeunless you deliberately need bulk or disabled command sync. - 8Only after the test channel works, add support threads, cron alerts, GitHub/CI notifications, or community moderation workflows.
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_CHANNELSfor dedicated mention-free bot rooms. - •Keep global mention gating enabled in mixed human channels.
- •Use
discord.thread_require_mention: truewhen 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.
- •Do not confuse the self-hosted Web UI monitoring dashboard with the full FlyHermes cloud experience.
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.
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 online but not responding: check the fail-closed user/role/channel policy first, then Message Content Intent, mention rules, and channel permissions.
- 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
Hermes Agent Discord setup guide
Full Developer Portal, bot token, intent, gateway, and troubleshooting sequence.
Connect Discord to Hermes checklist
Short setup checklist for the Discord gateway path.
Hermes WebUI dashboard
Use WebUI to verify gateway and platform health after setup.
FlyHermes managed cloud pricing
Choose the managed path when you do not want to operate Discord gateway infrastructure.
Hermes Docker Compose
Self-host long-running gateway services with Docker when you want full control.
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?
An online bot only proves Discord connected. Check the fail-closed access policy, privileged intents, mention rules, channel permissions, active Hermes profile, provider health, and one inbound event in the gateway logs.
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.