# How to set up Hermes Agent on Discord

> Connect Hermes Agent to Discord: create a bot, turn on Message Content Intent, invite it, set your allowlist and start the gateway.

Canonical: https://hermeswatcher.com/learn/hermes-agent-discord-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Compare interfaces at [messaging platforms](https://hermeswatcher.com/messaging.md).

- 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](https://discord.com/developers/applications).

- 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](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md).

## 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md).

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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md).

- 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md)

## Related tools

- [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md)
- [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md)
- [Discord: keep agent conversation scoped to the right people](https://hermeswatcher.com/tools/discord.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [Discord](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord)
- [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)
- [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773)
- [Scheduled delivery defaults](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt