How to set up Hermes Agent on Discord (bot, intents, allowlist)
Create the bot, turn on Message Content, give Hermes the token, invite it, restrict who can use it, run the gateway as a service, and fix a silent bot.
Create an application and bot in Discord’s Developer Portal, switch on Message Content Intent on its Bot page, and copy the token. On the server, run hermes gateway setup, pick Discord, and paste the token at its password prompt; the wizard checks it, offers to allow your own Discord account, and prints the invite link. Open the link to add the bot to your server, then keep the gateway running as a service. Hermes answers only the users you allow (everyone else is refused by default), replies to every DM, and in server channels answers only when @mentioned. If Message Content Intent is off, Discord refuses the connection and the bot never comes online. As of Hermes v0.23.2 (November 16, 2026).
In the Developer Portal
- New Application at discord.com/developers/applications and note its Application ID.
- On the Bot page, leave Require OAuth2 Code Grant off. Nous’s page says to turn Public Bot on if you will add the bot with the invite link the portal generates.
- Under Privileged Gateway Intents, turn on Message Content Intent. Turn on Server Members Intent too if you will allow people by username or by role. Presence Intent is not needed. Save Changes.
- Under Token, click Reset Token. The token is shown once; keep it somewhere you can paste from, not in a chat or a shared file.
A bot in fewer than 100 servers can switch these intents freely. At 100 servers or more, Discord’s gateway docs require the app to be verified and approved for each privileged intent first, which a bot for yourself never reaches.
Giving Hermes the token
The wizard is the route that never puts the token on screen or in your shell history:
hermes gateway setup # choose DiscordCopiedIn Hermes’s source at v0.23.2, it asks for “Discord bot token” as a password, checks it against Discord, and stops you if you pasted the numeric Application ID instead. If Message Content Intent is still off it says so and waits while you fix it in the portal. It then looks up who owns the application and asks “Allow yourself (@you) to talk to the bot?”, which is the easy way onto the allowlist without hunting for your user ID. Next come further allowed users, by ID or username, and a home channel ID (the channel Hermes posts unprompted messages to, settable later with /set-home). It saves the answers to ~/.hermes/.env as DISCORD_BOT_TOKEN, DISCORD_ALLOWED_USERS and DISCORD_HOME_CHANNEL.
One prompt reads “leave empty for open access”, but in v0.23.2 an empty answer with nobody already allowed saves nothing and warns “No allowlist set. Discord will deny messages until you set …”: the bot connects and answers no one.
To set it by hand instead, edit the file in an editor rather than typing the token into a command:
# ~/.hermes/.env
DISCORD_BOT_TOKEN=<token>
DISCORD_ALLOWED_USERS=284102345871466496CopiedYour user ID comes from Discord with Developer Mode on (Settings, Advanced), then right-click your name and Copy User ID.
The invite link
The wizard prints one. Built by hand, it is the Application ID with two scopes, bot and applications.commands, and a permissions number:
https://discord.com/oauth2/authorize?client_id=<application-id>&scope=bot+applications.commands&permissions=309237763136Copied117760is the minimum Nous lists: View Channels, Send Messages, Embed Links, Attach Files, Read Message History.309237763136adds Create Public Threads, Send Messages in Threads and Add Reactions; this is Nous’s recommended set.309240908864adds Connect and Speak for voice channels, and is the set the wizard’s own link asks for.
You need Manage Server on the server you add it to. Permissions in the link are a starting point: a channel or category with its own overrides can still hide that channel from the bot.
Who can talk to it
Since Hermes 0.18 the Discord adapter “fails closed”: with no access setting, it connects and refuses every message. Nous’s Discord page is plain about what an allowed user gets: “full access to the agent’s capabilities, including tool use and system access,” on the machine the gateway runs on. The settings, all in ~/.hermes/.env:
DISCORD_ALLOWED_USERS, comma-separated. Numeric user IDs are the safe form. Usernames work too, resolved to IDs when the bot connects, which needs Server Members Intent; display names and server nicknames are never matched, since anyone can set them.DISCORD_ALLOWED_ROLES, role IDs: anyone holding one is allowed. This also needs Server Members Intent, and makes everyone who can grant that role a gatekeeper of your server.DISCORD_ALLOWED_CHANNELSnarrows where it answers: “the bot only responds in these channels (plus DMs if allowed).”DISCORD_ALLOW_ALL_USERS=truelets anyone who can reach the bot use it; Nous limits it to “trusted/private guilds or development”. On a server with strangers in it, that is a shell for strangers.
Hermes picks whether to ask Discord for Server Members Intent at connect, so the first username or role added to an ID-only list takes a restart, and the intent must be on in the portal by then.
DMs, mentions and threads
In a DM, an allowed user gets an answer to every message, each DM with its own session. In a server channel Hermes stays quiet unless the message @mentions the bot, and also stays quiet when a message mentions other people but not the bot. To have it answer everything in chosen channels, list them in DISCORD_FREE_RESPONSE_CHANNELS; DISCORD_REQUIRE_MENTION=false does it everywhere. Replies in a thread stay in the thread, with history separate from the channel, and each person in a shared channel has their own session by default. Messages from other bots are ignored unless DISCORD_ALLOW_BOTS says otherwise, and the bot cannot ping @everyone, @here or a role unless you allow it.
Running it as a service
On a server the gateway belongs in systemd, not a terminal:
hermes gateway install
sudo loginctl enable-linger $USER
hermes gateway status
journalctl --user -u hermes-gateway -fCopiedWithout lingering, a user service stops when your last SSH session ends; the reason and the system-service alternative are in keeping a user service running after logout, and the rest of the server setup, including choosing one service rather than two, in installing Hermes on a server. Changes to ~/.hermes/.env take effect after hermes gateway restart. Hermes also writes its own log, ~/.hermes/logs/gateway.log, which is where Nous’s page points for the messages below.
The bot never comes online
Hermes always asks Discord for Message Content, so with that intent off Discord closes the connection with code 4014, “Disallowed intent(s)”, and does not let it reconnect. The library underneath, discord.py 2.7.1, raises PrivilegedIntentsRequired, whose own text says the shard “is requesting privileged intents that have not been explicitly enabled in the developer portal.” Hermes turns that into its own message:
Discord rejected the connection because privileged Gateway Intents are not enabled for this bot in the Developer Portal.
Hermes is requesting:
- Message Content Intent (required to read message text)
- Server Members Intent (required for username allowlists and/or DISCORD_ALLOWED_ROLES)CopiedThe second line appears only when your allowlist uses usernames or roles. Turn on what it lists, Save Changes, then hermes gateway restart. Nous calls it “a portal configuration error, not a flaky network issue,” so waiting does nothing.
A wrong or reset token is the other cause. Discord answers it with 4004, “Authentication failed”; discord.py’s error is “Improper token has been passed.”, and Hermes’s: “Discord bot token rejected: … The token is invalid or was revoked — regenerate it in the Discord Developer Portal and update DISCORD_BOT_TOKEN.” Resetting the token in the portal for any reason leaves the copy in .env in that state until you replace it.
Online, but it ignores you
- No access policy. The most common one: the log carries “No Discord access policy configured; inbound Discord messages will be denied by default.” Add your ID to
DISCORD_ALLOWED_USERSand restart. - You are not on the list. A username added since the last connect is not matched until a restart resolves it, and a nickname is never matched.
- No @mention in a server channel. Expected behaviour; mention the bot, DM it, or make the channel free-response.
- It cannot see the channel. Give the bot’s role View Channel and Read Message History in that channel’s permissions. A 403 Forbidden when it replies or opens a thread is the same problem on the sending side: re-invite with the recommended permissions or fix the override.
- The channel is outside
DISCORD_ALLOWED_CHANNELS, when that is set.
For what Hermes is beyond this one channel, and what else its gateway connects to, see what Hermes Agent is.