Hermes Agent Discord: bot setup, intents and access

Step 1: create the application and the bot

The Hermes documentation sends you to the Discord Developer Portal at discord.com/developers/applications. Sign in with your Discord account and create the bot like this:

1. Click New Application, name it (for example Hermes Agent), accept the terms and click Create.
2. Note the Application ID on the General Information page. You need it if you build the invite link by hand.
3. Open the Bot page in the left sidebar. Discord has already created a bot user for the application. Under Authorization Flow, the Hermes documentation recommends Public Bot on (it is required for the Discord-provided install link) and Require OAuth2 Code Grant off.

If you would rather keep the bot private, turn Public Bot off and build the invite link yourself, as described in Step 4. You can also set an avatar and banner on the same page.

Step 2: switch on the privileged intents

This is the step most people miss. On the Bot page, scroll to Privileged Gateway Intents. There are three switches: Presence, Server Members and Message Content. Without Message Content Intent enabled, Hermes cannot establish its Discord connection, because it requests that privileged intent on every start.

• Message Content Intent: always required. Hermes requests it on every start.
• Server Members Intent: only sometimes. The written guide lists it as required, but the code asks for it only when your allowlist contains usernames instead of numeric IDs, or when you use DISCORD_ALLOWED_ROLES. With numeric user IDs you can leave it off. Turning it on does no harm.
• Presence Intent: not needed.

Click Save Changes. If a requested intent is not enabled, Discord refuses the connection with a PrivilegedIntentsRequired error; see the errors section below. The Hermes documentation also notes that a bot in 100 or more servers needs Discord’s verification to use these intents, which does not matter for a personal or small-team bot.

Step 3: copy the bot token

Still on the Bot page, click Reset Token under the Token section, enter your two-factor code if Discord asks, and copy the token. Discord shows it once. If you lose it, reset it again and use the new one.

Treat it like a password: anyone holding the token controls your bot. Keep it in a password manager, do not paste it into public chats and do not commit it to Git. Resetting the token also signs out whatever was using the old one, so update Hermes straight afterwards.

Step 4: invite the bot to your server

The invite is an OAuth2 link with the bot and applications.commands scopes. The second one is what lets Hermes register slash commands. There are two routes:

• Installation tab: enable Guild Install, set Install Link to Discord Provided Link, and under Default Install Settings choose the two scopes and the permissions below. This needs Public Bot on.
• Manual link: use https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands with your Application ID in place of YOUR_APP_ID, and add a permissions value if you want the permissions preselected. This works for private bots too.

The Hermes documentation lists these as the minimum permissions:

• View Channels
• Send Messages
• Embed Links
• Attach Files
• Read Message History

For the default auto-threading behaviour, also grant Create Public Threads and Send Messages in Threads. Add Reactions enables progress reactions. Open the link, pick your server in the Add to Server list, then Continue and Authorize. You need the Manage Server permission on that server; if your server is not listed, ask an admin to use the link. The bot appears in the member list, offline until Hermes connects.

Step 5: give Hermes the token and say who may use it

Hermes decides who can talk to the bot by Discord user ID. In Discord, open Settings, Advanced, and turn on Developer Mode. Then right-click your own name and choose Copy User ID. You get a long number such as 284102345871466496. The same menu copies channel IDs, server IDs and role IDs.

The guided route is hermes gateway setup: choose Discord and paste the token and your user ID. To edit files yourself, put this in ~/.hermes/.env:

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

Separate several IDs with commas. Then run hermes gateway (or install it as a service with hermes gateway install) and the bot comes online within seconds. If Hermes is not installed yet, start with how to install Hermes Agent.

Other ways to let people in:

• DISCORD_ALLOWED_ROLES: comma-separated role IDs. Anyone holding one of those roles in the server is allowed, alongside any listed users. This is the one that needs the Server Members intent.
• DISCORD_ALLOWED_CHANNELS: with no user or role list at all, channel IDs here let people talk to the bot in those server channels. It is not a bypass for direct messages.
• DISCORD_ALLOW_ALL_USERS=true (or GATEWAY_ALLOW_ALL_USERS=true): permits otherwise unlisted users only when both the user and role allowlists are empty. Channel restrictions still apply. The Hermes documentation restricts open access to trusted servers or development, because an authorised user has the agent’s full tool access.
• Pairing: a person approved in Hermes’ pairing store is accepted by the Discord adapter even if they are not in the allowlist.

The safe default matters. With no user or role allowlist, no allowed channels and no allow-all flag, Hermes rejects messages from users who have no pairing approval. When it rejects traffic under this empty policy, it logs “Discord messages are being denied because no allowlist is configured.”

Servers, channels, mentions and threads

These are the defaults in version 0.21.5, and the settings that change them.

• Direct messages: Hermes answers every message from an allowed person, no mention needed, and each DM has its own session.
• Server channels: by default it replies only when you @mention it (DISCORD_REQUIRE_MENTION, default true). For a channel where people should chat freely, list its ID in DISCORD_FREE_RESPONSE_CHANNELS. Setting DISCORD_REQUIRE_MENTION=false removes the mention rule everywhere.
• Other people’s conversations: by default, DISCORD_IGNORE_NO_MENTIONdrops messages that mention other people without mentioning Hermes, except in free-response channels and threads Hermes has joined. Messages that mention another bot without mentioning Hermes are rejected separately.
• Threads: DISCORD_AUTO_THREAD defaults to true. Eligible top-level messages create a thread; reply messages skip auto-threading. Hermes normally continues in threads it has joined without another mention. Free-response channels answer inline unless DISCORD_FREE_RESPONSE_AUTO_THREAD=true. Use DISCORD_NO_THREAD_CHANNELS for inline replies in selected channels. DISCORD_THREAD_REQUIRE_MENTION=true removes the joined-thread exemption, but free-response settings and DISCORD_REQUIRE_MENTION=false still permit mention-free replies.
• Who shares a conversation: ordinary shared-channel sessions are isolated per user by default, but thread sessions are shared. Keep group_sessions_per_user: true and set thread_sessions_per_user: true in config.yaml to isolate users inside threads too. Set group_sessions_per_user: false to share ordinary channel sessions.
• Blocking channels: DISCORD_IGNORED_CHANNELS lists channels where the bot never replies, even when mentioned.
• Other bots: DISCORD_ALLOW_BOTS is none by default, so Hermes ignores other bots.
• Pings: the bot cannot ping @everyone, @here or roles by default, even if its reply contains them. That is deliberate, since a model can easily echo those words.

Supported Discord settings such as require_mention, auto_thread and free_response_channels can be set under discord: in ~/.hermes/config.yaml; their explicit environment variables take precedence. Session settings belong at the top level or under gateway:. DISCORD_IGNORE_NO_MENTION is read from the environment.

Voice, files and slash commands

• Voice messages you send are transcribed and handed to the agent as text, using the speech-to-text provider you configure: local faster-whisper, a hosted provider, or the transcription included with a Nous subscription. /voice tts turns on spoken replies, and the documentation describes Hermes joining a Discord voice channel, listening and talking back. Voice channels need extra setup; the desktop app and the voice-mode guides in the Hermes docs go further.
• Files: all file types are accepted; DISCORD_ALLOW_ANY_ATTACHMENT is a legacy no-op. Documents and other non-image, non-audio attachments have a default 32 MiB cap controlled by DISCORD_MAX_ATTACHMENT_BYTES. Setting it to 0 removes that Discord-specific cap; separate gateway media limits still apply. Images and audio use separate handling. Outgoing files are subject to Discord’s upload limit for the destination.
• Slash commands: Hermes registers native commands such as /model, /voice and /sethome. Installed skills are selected through /skill autocomplete, subject to catalog filtering and name collisions. Discord limits native commands to 100 per application; skills share that one command. /model with no argument opens dropdowns to pick a provider and model. Registration happens at gateway start. Allowed users can be split into admins and regular users, with regular users limited to commands you list plus /help and /whoami.
• Home channel: run /sethome in a channel, or set DISCORD_HOME_CHANNEL, so scheduled-job results and reminders have somewhere to go.
• Reactions: Hermes adds an eye when it starts, a tick on success and a cross on error. DISCORD_REACTIONS=false turns that off.

Common errors and fixes

• The bot is online but never replies. Check its access policy, mention requirements and channel permissions. If the gateway instead reports PrivilegedIntentsRequired, enable the requested intents in the Developer Portal. Restart the gateway after configuration changes.
• PrivilegedIntentsRequired on start. Hermes asked for an intent that is off. Enable Message Content, and Server Members if you use usernames or roles, click Save Changes and restart. The log names the intents Hermes requested.
• It works in DMs but not in a channel. Check the mention rule, free-response settings, channel restrictions and thread permissions. Mentioning another person without mentioning Hermes can also suppress a reply outside free-response channels and joined bot threads.
• It cannot see one channel. The bot’s role lacks View Channel and Read Message History there. Fix it in the channel’s permission settings.
• 403 Forbidden. A permission is missing. Re-invite with the permissions above, or adjust the bot’s role under Server Settings.
• The bot stays offline. The gateway is not running, or the token is wrong or was reset. Update DISCORD_BOT_TOKEN and restart.
• Slash commands do not appear. The invite must include applications.commands. Commands sync at gateway start, and DISCORD_COMMAND_SYNC_POLICY (default safe, or off to skip syncing) controls how.
• Discord is blocked on your network. Set DISCORD_PROXY (http, https or socks5).

As with any chat channel, the bot answers only while the gateway is running, so a laptop that sleeps means a silent bot. Our comparison of self-hosting and managed hosting covers when an always-on host is worth it.

Discord on ReadyHermes

On ReadyHermes your Hermes Agent runs on our servers and stays online, so there is no gateway for you to start. Discord is one of the channels in the workspace, next to Telegram, WhatsApp, WeChat and Lark. You still create the bot yourself:

1. Do Steps 1 to 3 above: create the application, turn on Message Content Intent, copy the token.
2. In the workspace, open Channels, choose Discord, paste the bot token and connect. Your assistant restarts to apply it, which takes about a minute.
3. Invite the bot to your server with a link like the one in Step 4, then message it or @mention it.

What ReadyHermes sets up for you:

• It validates the bot token with Discord before applying the connection. It also checks Message Content Intent and refuses the connection if Discord confirms that the intent is disabled. If that intent check is unavailable, the connection proceeds and the gateway may still reject the missing intent.
• It writes an open allowlist (allow_from set to a wildcard) for Discord. Discord’s connect step only collects the bot token, so ReadyHermes cannot know your own Discord user ID; an empty allowlist would make the bot ignore everyone, including you. In practice anyone who can reach the bot can use it, in a DM or in a server where it is present, and no pairing code is expected. The Channels panel has no field for restricting Discord to certain users or roles.
• Use a separate Discord bot for each assistant. ReadyHermes refuses a token that another of its assistants already uses, but it cannot see a copy of the token running somewhere else, so do not run the same bot elsewhere at the same time.
• ReadyHermes keeps the Hermes defaults for mentions, threads and channels, and the Channels panel has no controls for them.

Because the allowlist is open, anyone who can reach the bot can use it, including through DMs. Turn Public Bot off to restrict who can install it, add it only to trusted servers, and control their membership. Keeping the invite URL private does not restrict who may message an installed bot. You can disconnect Discord from the same panel at any time. The Channels panel needs an active trial or paid plan. For the wider picture, read about managed Hermes Agent hosting.