Integration
Hermes Agent Discord Setup: Bot, Permissions & Threads
Set up Hermes Agent on Discord with a bot token, intents, fail-closed access, mention rules, per-user sessions, threads, gateway checks, and a real reply test.
Quick answer
Create a Discord application and bot, invite it with bot plus applications.commands, enable the required privileged intents, then run hermes gateway setup. Configure at least one allowed user, role, or channel because Hermes fails closed without an access policy. Reload the gateway and prove the path with one real reply in the exact DM, channel, thread, or forum post. An online bot and a green Web UI are checkpoints—not end-to-end proof.
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 health checks through
hermes gateway status, logs, and the Hermes Web UI - ✓Dedicated Hermes profiles so community bots receive only the intended secrets, memory, skills, and tools
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. - 7Only 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.
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.
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.