Hermes Agent Discord Setup Guide

This page owns one search intent: Hermes Agent Discord setup. The goal is to get one Discord bot working in one safe channel, verify the Hermes gateway path, and only then expand to threads, community support, cron alerts, or team workflows.

Why this guide was upgraded#

Recent community evidence points directly at Discord setup and gateway reliability. The May Discord scrape found 122 messaging-platform threads, including Discord adapter errors, unauthorized thread behavior, Docker/gateway confusion, and users asking whether gateway restarts belong in terminal or chat. Google Search Console also shows page-one impressions with weak CTR for hermes agent discord, hermes agent discord integration, hermes agent discord setup, and hermes agent discord bot setup.

That means the page should not be a generic integration pitch. It should answer the setup problem, route decision-stage readers to the Discord integration overview, and route ops-heavy readers to FlyHermes pricing when they want the outcome without owning the gateway stack.

Discord setup intent vs the other pages#

Keep the cluster clean:

• Use this setup article when you need the full Discord Developer Portal and Hermes gateway sequence.
• Use the Discord integration page when you are deciding whether Discord fits team support, community, or channel workflows.
• Use connect Discord to Hermes when you want the shortest implementation checklist.
• Use fix Docker Discord container issues if the Discord gateway sees the wrong filesystem, config, or environment after a container restart.
• Use Hermes Agent VPS hosting when the bot works locally but needs always-on uptime.
• Use the Hermes Agent troubleshooting guide if the model, tool, or provider layer is failing before Discord receives a message.

Step 1: choose the Discord workflow#

Before touching the Developer Portal, decide how the bot should behave. Discord has more permission surfaces than Telegram: server roles, channel overrides, app mentions, slash commands, forum threads, and message-content access.

A safe default is:

1. One test server.
2. One private channel.
3. App mentions or slash commands first.
4. Message Content Intent only if the bot must read normal channel text.
5. A dedicated Hermes profile for the Discord bot if the server includes teammates or community members.

That profile boundary matters. A community bot should not automatically inherit every local secret, skill, browser session, or filesystem assumption from your personal CLI agent. If you need hard isolation, use Hermes Agent profiles.

Step 2: create the Discord app and bot#

In the Discord Developer Portal:

1. Create a new application.
2. Add a bot user.
3. Copy the bot token once and store it in the active Hermes profile environment.
4. Enable Message Content Intent only if the workflow requires reading regular messages.
5. Generate an invite URL with the narrowest scopes needed for your test.
6. Invite the bot to the test server and private test channel.

Do not paste the token into prompts, screenshots, Git commits, Docker Compose files, or a shared team chat. Treat it like any other gateway credential.

Step 3: configure Hermes gateway#

Use the Hermes gateway setup path rather than mixing manual edits and half-restarted processes:

hermes gateway setup
hermes gateway restart
hermes gateway status

If you maintain multiple bots or trust levels, create a dedicated profile first:

hermes profile create discord-bot
hermes -p discord-bot gateway setup
hermes -p discord-bot gateway restart

The dedicated profile keeps Discord-specific config, memory, skills, and secrets away from the rest of your local Hermes setup.

Step 4: verify the gateway before adding more channels#

Run a real end-to-end check before expanding access:

hermes gateway status
hermes status --all

Then open the Hermes WebUI dashboard and check gateway/platform health. Finally, send one Discord mention or slash command in the test channel. If it works, inspect whether the answer is scoped correctly before adding forum threads, support rooms, GitHub alerts, or cron digests.

For a long-running service, pair this with Hermes Docker Compose or the VPS deployment guide, but remember the maintenance cost: process managers, env files, gateway logs, Docker updates, TLS, and restarts. If that is not the work you want, FlyHermes is the managed option.

Troubleshooting map#

Bot is online but Hermes does not answer#

Check these in order:

• Is the message an app mention or slash command if free-response is disabled?
• Does the bot have channel access and permission to send messages?
• Is Message Content Intent enabled if you expect normal message reading?
• Did you restart the gateway after changing tokens, channels, or profile config?
• Does hermes gateway status show Discord connected?
• Do recent Hermes logs show the inbound Discord message?

Works locally but not in Docker or on a VPS#

This is usually an environment mismatch. Confirm the service can read the same profile, token, and config that worked locally. Then inspect container/service logs. The Docker Discord troubleshooting guide is the right page if the bot starts from the wrong directory, reads the wrong .env, or loses gateway state after restart.

Threads or forum channels behave differently#

Test in layers: normal channel first, private thread second, public/forum thread third. If normal channels work but threads fail, the problem is probably thread permissions, bot membership, or gateway thread handling rather than the model provider. Use the Discord integration page for the decision framework and this setup guide for the operational checks.

The bot responds in places it should not#

Narrow the deployment. Use channel allowlists, role permissions, app mentions, and a dedicated Hermes profile. For community servers, safer defaults beat convenience: a permission mistake can expose a tool-using agent to the wrong audience.

Self-hosted Discord bot vs FlyHermes#

Self-host when you want full control over the machine, profile, tools, secrets, logs, and gateway behavior. That is the right choice for developers who already run servers and want local ownership.

Use FlyHermes when you want the Discord/mobile/channel outcome without maintaining the bot stack. The trade is simple: self-hosting gives maximum control; FlyHermes pricing buys managed uptime, browser access, mobile access, and fewer gateway chores.