How to Set Up Hermes Agent on Discord (Bot + Voice)

Why Run Hermes Agent in Discord

If your project, studio, or friends already hang out in a Discord server, that is where your agent should be reachable from. Threads, voice channels, and role-gated rooms all give Hermes context that a standalone dashboard cannot: who is asking, what channel they are in, whether they are speaking or typing, and where the answer should land.

Hermes Agent ships first-class Discord support that covers both the text and voice sides of a server. The runtime connects out to Discord over the standard Gateway WebSocket, so it can sit on your laptop, on a small VPS, or behind a home NAT and still stream messages in real time. There is no public webhook to expose and no inbound port to open. The same runtime that answers text messages can also join a voice channel with /voice join, listen through STT, and reply out loud through TTS.

This guide walks through the full setup end to end: creating the Discord application, generating the bot token, enabling the intents that Discord silently requires, wiring the allowlist and home channel, inviting the bot with the correct OAuth2 URL, and the failure modes that catch first-time deployments.

What You Need Before You Start

A clean Discord deployment needs five things in place:

• A Discord server where you have permission to add bots. If it is not your server, ask the admin, the invite URL only works for someone with "Manage Server" on the target guild.
• A running Hermes Agent install. The Hermes Agent Docker guide is the cleanest way to get one up; if you are on Windows, the WSL2 setup is the equivalent.
• A model provider key. Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible endpoint works. The runtime uses it to answer messages.
• Your numeric Discord user ID for the allowlist (Developer Mode → right-click your name → Copy User ID).
• About 15 minutes for the first install. Subsequent re-deployments take under a minute.

Step 1 - Create the Discord Application and Bot

Open the Discord Developer Portal, click New Application, name it (for example, hermes-agent), and accept the developer terms. This creates an application container that will hold the bot user, the OAuth2 credentials, and the token.

From the application page, go to Bot in the sidebar. Discord no longer requires you to click Add Bot on new applications, the bot user is created automatically. What you do need to do is give it a display name, an avatar, and toggle Public Bot off if you want the invite URL to be usable only by you.

Then click Reset Token to reveal the bot token. It looks like MTA…. Copy it once and paste it straight into your .env, Discord will never show it to you again, only let you reset it.

Treat this token like an SSH key. Anyone with the token can act as your bot, read every message in every channel the bot is in, and burn your model provider tokens by triggering the agent.

Step 2 - Enable the Gateway Intents Discord Requires

This is the step that silently breaks the most Discord bot deployments. Discord splits "what Discord sends your bot" into intents. A few of them are privileged, meaning you have to explicitly opt in for every application, or Discord will connect the WebSocket, deliver events, and simply strip out the fields you have not asked for.

Still in Bot, scroll to Privileged Gateway Intents and enable:

• Message Content Intent - required to read the text of messages. Without it, Hermes receives message events with empty content and stays silent forever.
• Server Members Intent - required to resolve the allowlist against real member IDs and to see when members join or leave.
• Presence Intent - optional, useful if you want the bot to react to a user going online or entering a voice channel.

Click Save Changes at the bottom of the page. This has to be done in the Developer Portal, there is no .env toggle for it.

Once your bot is verified and used in more than 100 servers, Discord makes you apply for these intents. Below that threshold, the toggles are all you need.

Step 3 - Find Your Numeric Discord User ID

Hermes Agent will only respond to user IDs that appear in DISCORD_ALLOWED_USERS. This is the single most important security control in the whole setup, and it expects numeric IDs, not @handles.

In Discord, open User Settings → Advanced → toggle Developer Mode on. Then close settings, right-click your name in any channel or member list, and pick Copy User ID. The ID looks like 284102345871466496. Repeat for any teammate you want to authorize.

Skipping the allowlist is the same as publishing your provider API key to the entire server. If a Hermes instance is reachable from a public server with an empty allowlist, every message the bot can read will burn your tokens and, in a voice channel, every noise it can hear will get transcribed.

Step 4 - Configure the Hermes Runtime

Open ~/.hermes/.env (or whichever .env your container reads) and add:

DISCORD_BOT_TOKEN=MTA...your-bot-token...
DISCORD_ALLOWED_USERS=284102345871466496,297811223344556677
DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

A note on each:

• DISCORD_BOT_TOKEN - the token you copied in Step 1.
• DISCORD_ALLOWED_USERS - comma-separated list of numeric user IDs. The bot ignores everyone else, including server admins and other bots.
• DISCORD_HOME_CHANNEL (optional) - the channel ID for proactive messages, scheduled task output, and skill-triggered notifications. Right-click the channel in Discord → Copy Channel ID. If unset, proactive output goes to the bot's DM with the first allowed user.
• DISCORD_HOME_CHANNEL_NAME (optional) - a human-readable label used in logs, does not affect routing.

chmod 600 ~/.hermes/.env after saving. The token grants full access to your bot; treat it like an SSH key.

Step 5 - Invite the Bot to Your Server

Bots do not join servers, they are invited via an OAuth2 URL that requests the right scopes and permissions up front. The scopes and permissions Hermes expects are:

• Scopes: bot and applications.commands (the second one enables the /voice slash commands).
• Permissions integer: 274878286912, which covers View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Send Messages in Threads, and Add Reactions.

Take your application's Client ID from General Information in the Developer Portal and drop it into this template:

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

Open the URL, pick your server, confirm the permissions, and Discord will drop the bot in as a member. You can also build the URL from OAuth2 → URL Generator in the portal if you prefer clicking checkboxes, the result is the same.

For voice, you will also want Connect and Speak on the specific voice channel you plan to use. If they are missing after the invite, add a role to the bot that grants them or edit the channel's permission overwrites directly.

Step 6 - Start the Gateway and Send the First Message

Restart the gateway so it picks up the new environment:

hermes gateway restart

Or, with Docker Compose:

docker compose restart gateway

Tail the logs and watch for the Discord handshake:

hermes gateway logs --follow

You are looking for two lines, in order:

discord: connecting to Gateway
discord: connected as your-bot-name#1234 (guilds: 1)

If you see the first line and nothing after, the token is wrong or has been rotated. If the bot connects but never responds to a message in the channel, Message Content Intent is still off in the portal, or your user ID is not in DISCORD_ALLOWED_USERS.

Once it is up, send it a DM or @-mention it in a channel it can see. Hermes responds in the same conversation, with full memory and skill context intact. From here, every Hermes capability, persistent memory, scheduled tasks, and custom skills, works exactly as it does on the Telegram delivery surface.

Step 7 - Turn On Voice (Optional but Fun)

Discord voice channels are a first-class surface for Hermes. Once the bot is in the server with Connect and Speak, join a voice channel yourself and, in any text channel the bot can see, type:

/voice join

The bot will join the voice channel you are currently in, start listening through the STT provider you configured, and reply out loud through the TTS provider. The full command surface is:

• /voice join - join your current voice channel.
• /voice channel - alias of /voice join.
• /voice leave - disconnect from the voice channel.
• /voice status - report whether voice mode is on and which channel the bot is in.

Only users in DISCORD_ALLOWED_USERS are transcribed; other people's audio is ignored, which matters if the voice channel is shared with people you have not explicitly authorized. For details on picking an STT/TTS stack that works well over Discord's Opus stream, the Hermes voice mode overview is the right next read.

The Failure Modes That Bite First

Five mistakes account for almost every "Discord setup is broken" support thread:

Message Content Intent still off. The bot connects, joins the server, and responds to nothing. Discord will not warn you. Toggle it on in the portal and restart the gateway.

Empty DISCORD_ALLOWED_USERS. The default is to ignore everyone. Deliberate safe default, but it makes the bot look broken to a first-time tester who forgot to add their own ID.

Wrong permissions on invite. If the bot cannot see the channel, or lacks Send Messages, it stays silent even for authorized users. Re-invite with the 274878286912 permissions integer or fix the role in Server Settings → Roles.

Voice permissions missing on a specific channel. The bot has Connect and Speak at the server level but a channel overwrite removes them. Discord shows the bot as "connected" but produces no audio in either direction. Check the voice channel's permission tab.

Two gateway processes against the same data volume. If you start a Discord-mode gateway and a Telegram-mode gateway against the same /data directory, message ordering and memory writes corrupt each other within minutes. Run a single gateway with both DISCORD_* and TELEGRAM_* blocks set in .env if you want both surfaces, the runtime multiplexes both natively.

If a problem looks Discord-shaped but the symptoms feel general, the Telegram troubleshooting guide covers the underlying gateway and provider issues in more depth, most are surface-agnostic.

Discord and Telegram, Side by Side

The two surfaces are not exclusive. The same Hermes runtime can serve both at the same time, useful when a personal Telegram chat and a shared Discord voice room draw from the same memory store.

Skip the Discord Plumbing

The steps themselves are straightforward, but you still own the host: backups, TLS for the dashboard, log rotation, and the upgrade cadence. For a personal-scale install that is fine. For a server that wants the bot live within minutes and no operational overhead afterward, Hermify provisions a managed Hermes runtime on Telegram, keeps memory persistent, and rotates the tokens without you touching a .env.

You bring the model provider key and the surface you want to use; the platform handles everything below. If you are evaluating that trade-off before you invest in your own VPS, the self-hosting vs managed comparison walks through the cost and maintenance numbers.

Sources

• Hermes Agent Discord setup docs (mirror)
• Hermes Agent messaging gateway overview
• Hermes Agent voice mode
• Discord Developer Portal - Applications
• Discord gateway intents reference