How to set up Hermes Agent on Discord

What you need

Hermes Agent can run as a Discord bot, so you can chat with your agent in direct messages or server channels. It supports text, voice messages, file attachments and slash commands.

Authorized DMs need no @mention. Server channels normally require an @mention, and every request must still pass the access policy. For background, see Hermes Agent messaging gateway explained. Compare interfaces at messaging platforms.

• Hermes Agent installed, with a model provider configured.
• A Discord account, and access to the Discord Developer Portal.
• The Manage Server permission on the server you want to add the bot to.
• Your numeric Discord user ID. The steps below show how to find it.

Create the bot and invite it

Everything here happens in the Discord Developer Portal↗ (opens in a new tab).

• Click New Application, enter a name such as "Hermes Agent", accept the Developer Terms of Service and click Create. Note the Application ID on the General Information page.
• Click Bot in the left sidebar. Under Authorization Flow, set Public Bot to ON. This lets anyone with the invite link add it to a server, while the Hermes allowlist still decides who can use the agent. To stop others adding it, leave Public Bot OFF and use the manual invite link below. Leave Require OAuth2 Code Grant OFF in either case.
• Under Privileged Gateway Intents, enable Message Content Intent. Enable Server Members Intent when using username or role allowlists; numeric user-ID-only authorization does not itself require it. Presence Intent is optional. Save Changes.
• Under Token, click Reset Token and copy the token. Discord shows it only once.
• Click Installation. Under Installation Contexts, enable Guild Install. Set Install Link to Discord Provided Link. Under Default Install Settings, select the scopes bot and applications.commands and the permissions you need.
• Open the invite link, pick your server in the Add to Server dropdown, click Continue, then Authorize.

Manual invite URL (replace YOUR_APP_ID)

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

Message Content Intent is easy to miss. Hermes always asks Discord for message content, so if the intent is off, Discord refuses the connection and the bot never comes online.

If you keep the bot private (Public Bot OFF), use the manual URL above instead of the Installation tab. Its permissions number is the docs' recommended set.

Never share the token or commit it to Git. Anyone with it has full control of your bot. The bot shows as offline in your server until you start the gateway.

Keep the recommended manual invite permission integer 309237763136. The setup wizard prints 309240908864 when requesting Connect and Speak for voice channels. Invite permissions and Gateway Intents are separate controls.

Connect it to Hermes

To find your user ID, open Discord, go to Settings → Advanced and turn Developer Mode ON. Then right-click your own username and choose Copy User ID. It is a long number like 284102345871466496.

Run the setup wizard, select Discord and paste your bot token. The wizard checks the token with Discord, checks the privileged intents, prints the invite link and offers to allowlist you as the bot's owner. To configure it by hand instead, add the lines below to ~/.hermes/.env. Separate multiple user IDs with commas.

Terminal

hermes gateway setup

~/.hermes/.env (manual option)

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

Only authorize people you trust. An allowlist, an approved pairing or another supported explicit grant can authorize agent work. An allowlist is the list of permitted users, roles or chats. DISCORD_ALLOWED_CHANNELS can scope access to whole channels, so consider who can post there. Keep allow-all disabled on a private bot. Authorized users can use the profile's configured tools, including terminal and file access, subject to its security settings.

For servers where access follows roles, set DISCORD_ALLOWED_ROLES to a comma-separated list of role IDs. Anyone with one of those roles is authorized, alongside the user list.

New DM pairing codes are not promised when a restrictive policy or explicit allowlist is set. Inspect the gateway log and hermes pairing list rather than widening access to diagnose silence.

Start the gateway and send your first message

Start the gateway in the foreground first so you can watch it connect.

Terminal

hermes gateway

With the gateway running, send a harmless DM from an authorized account, or @mention it in a channel it can see. Check that the reply reaches that conversation and inspect the gateway output for errors.

Use /sethome in a supported channel to choose the home destination for a bare discord delivery target. Chat-created scheduled jobs default to their origin, CLI-created jobs to local output, and explicit targets select their own channel. See Hermes Agent task finished but no message arrived.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

A foreground gateway stops when you close the terminal. Install it as a background service instead. The docs describe a user systemd service on Linux, a launchd service on macOS, and a Scheduled Task that runs at logon on Windows.

Install the service

hermes gateway install

Start it

hermes gateway start

Restart after changing settings

hermes gateway restart

Check the running service

hermes gateway status

For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server. For how the gateway handles sessions and platforms, see Hermes Agent messaging gateway explained.

If the host is off, asleep or offline, the bot cannot answer and scheduled jobs cannot run. Windows Task Scheduler watches the launcher, not later gateway crashes. Check the actual running state and use hermes gateway start if it has stopped.

Servers, channels and permissions

• Mentions: DISCORD_REQUIRE_MENTION defaults to true for server channels. Authorized DMs need no mention, but must still pass the access policy.
• Mention-free channels: list IDs in DISCORD_FREE_RESPONSE_CHANNELS to remove the tagging requirement. This changes triggers, not authorization. Replies stay inline by default in these channels.
• Threads: DISCORD_AUTO_THREAD defaults to true for top-level mentions in text channels. Mention-free channels skip auto-threading by default; discord.free_response_auto_thread: true enables it there. Existing threads keep their own session history.
• Shared channels: each user gets their own session inside a channel by default (group_sessions_per_user: true), so two people in one channel do not share a transcript.
• Channel limits: DISCORD_ALLOWED_CHANNELS restricts the bot to listed channels. DISCORD_IGNORED_CHANNELS lists channels where it never responds.

If it doesn't answer

Most Discord issues come from intents, the access policy or channel permissions. For a wider checklist, see Hermes Agent bot not responding in your chat app.

• Bot stays offline and the log mentions privileged intents: enable Message Content Intent and Save Changes. Enable Server Members Intent if you use username or role allowlists. Then run hermes gateway restart.
• Bot is online but silent: inspect the gateway log for an access-policy error, then check the allowed user, role or channel and approved pairings. For a private numeric-ID setup, add your own DISCORD_ALLOWED_USERS value and restart.
• Bot is offline: check that hermes gateway is running and that DISCORD_BOT_TOKEN is correct. If you reset the token, update it.
• Bot ignores you: check the access policy first, then channel visibility and mention rules. An allowlist entry, approved pairing or supported role/channel grant must admit the request.
• Bot cannot see one channel: in that channel's Permissions, give the bot's role View Channel and Read Message History.
• 403 Forbidden errors: re-invite the bot with the correct permissions, or adjust its role in Server Settings → Roles.

What it can do

The overview lists voice, images, files, threads, reactions, typing and streaming for Discord. Actual media and speech use still depends on the configured model, providers and permissions. Voice-message transcription and spoken replies are distinct from joining a live Discord voice channel.

Local faster-whisper is the normal local transcription engine where supported. Native Windows ARM64 and Intel macOS need a supported hosted or command-based provider instead. Live voice additionally needs the documented voice dependencies and Connect/Speak permissions.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Discord docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher