Connect Hermes Agent to Discord: Setup & Troubleshooting Guide

Connecting Hermes Agent to Discord takes 15 minutes and comes down to creating a bot token, enabling the Message Content Intent (the gotcha that breaks most setups), and running hermes gateway setup. This guide covers every step, including the verification checklist and troubleshooting for when the bot goes online but stops responding.

Before You Start: What Hermes Needs from Discord

Hermes Agent interacts with Discord through a gateway process. You define what the agent can access (intents), who can talk to it (access policies), and which channels it monitors. Discord enforces strict permissions. If your bot doesn't respond, it's almost always because the bot is missing read/write permissions, the Message Content Intent is disabled, or the gateway process is not running.

Three things need to be true: the Discord bot has explicit permission to read messages in the channel, the Message Content Intent and Server Members Intent are enabled in Developer Portal, and the Hermes gateway is running and connected to Discord.

Hermes respects context. In a direct message (DM) to your bot, it acts as a 1:1 assistant. In a channel, it only processes messages that mention it or reply to its messages. In threads, the same rules apply: the bot sees the thread as isolated from the parent channel. This behavior prevents the agent from getting noisy or responding to off-topic conversation.

You can also restrict access by user ID, role, or allow all users. This is set in the .env file via DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES, or DISCORD_ALLOW_ALL_USERS.

Step 1: Create Your Discord Application in Developer Portal

1. Go to https://discord.com/developers/applications.
2. Click "New Application" in the top right.
3. Name it (e.g., "My Hermes Agent").
4. Accept the ToS and click "Create".
5. You're now in the app overview. Copy the APPLICATION ID for OAuth scopes (if needed later).

In the left menu, click "Bot" and then "Add Bot". This creates your bot user within the application.

Under the bot settings, you'll see a TOKEN field. This is your bot's password. Copy it and store it securely in a password manager or .env file, never in git. If you accidentally commit it to GitHub, regenerate it immediately: anyone with the token can control your bot.

Scroll down to "Privileged Gateway Intents". This is where you enable what Discord calls "intents": the specific events your bot can receive. You need at least two: Message Content Intent (without this, your bot can't read the content of messages in channels it doesn't own; this is the #1 reason bots appear offline but don't respond) and Server Members Intent (lets your bot see who's in the server and enforces role-based access policies).

Toggle both ON (the switch should be blue). Save changes at the bottom of the page.

Next, set permissions. In the left menu, click "OAuth2" > "URL Generator". Under scopes, check "bot". Under permissions, select Send Messages, Read Message History, Read Messages/View Channels, and Embed Links (optional, for formatted responses). Copy the generated URL at the bottom, open it in a new tab, select the server you want to add the bot to, click "Authorize", and solve the CAPTCHA. Your bot is now in the server with the right permissions.

Step 2: The Critical Step Everyone Misses -- Enable Privileged Intents

This section deserves its own heading because it's the single most common reason Discord bots appear online but don't respond.

When you created your bot in Developer Portal, you toggled on "Message Content Intent" and "Server Members Intent". But there's a second place you need to enable intents: in your Hermes configuration. When you run hermes gateway setup (covered in Step 5), the setup wizard will ask which intents you want. By default, it may not enable MESSAGE_CONTENT. You must explicitly set all five: MESSAGE_CONTENT, GUILD_MEMBERS, GUILDS, GUILD_MESSAGES, DIRECT_MESSAGES.

If you're editing .env manually instead of using the wizard, the variable is:

DISCORD_INTENTS=MESSAGE_CONTENT,GUILD_MEMBERS,GUILDS,GUILD_MESSAGES,DIRECT_MESSAGES

What do these intents mean? MESSAGE_CONTENT reads the actual text of messages. Without this, your bot sees "a message arrived" but not what the message says: useless. GUILD_MEMBERS lets you see who joined/left the server and enforce role-based access control. GUILDS monitors basic server events (channel create, role changes). GUILD_MESSAGES receives messages in channels (not just DMs). DIRECT_MESSAGES receives DMs sent to the bot.

If the bot is in the server, permissions are correct, but it still doesn't respond, restart the gateway with hermes gateway restart. The gateway caches intent state on startup. If intents changed after the gateway started, the old config is still in memory.

Step 3: Generate and Secure Your Bot Token

In Developer Portal, go to Bot and copy the TOKEN. Store this token securely: not in your repository (use .env and add .env to .gitignore), not in Slack or email, in a password manager (1Password, Bitwarden) or secrets management tool if you're running in production.

If you accidentally exposed the token, regenerate it immediately. Go to Bot, find the TOKEN field, and click "Regenerate". The old token stops working within seconds.

For self-hosted Hermes, paste this token into the .env file as:

DISCORD_TOKEN=<your-token-here>

For managed Hermes hosting, you'll paste it into the environment variables during deployment. The platform encrypts it at rest.

Step 4: Configure Access -- Who Can Talk to Your Agent?

Hermes on Discord supports three access control modes. Choose one:

Allow All Users (Simplest): Set DISCORD_ALLOW_ALL_USERS=true. Any user in the server can mention the bot and get responses. Use this for public channels or trusted internal teams.

Allowlist by User ID (Most Common): Set DISCORD_ALLOWED_USERS=123456789,987654321,111222333. Replace the numbers with Discord user IDs. Only those users get responses. Find your user ID by enabling Developer Mode in Discord settings, right-clicking your name, and clicking "Copy User ID".

Allowlist by Role (Teams/Departments): Set DISCORD_ALLOWED_ROLES=admin,engineers,product. Only users with those roles can talk to the bot. This scales better than user lists in teams over 30 people.

You can combine them:

DISCORD_ALLOW_ALL_USERS=false
DISCORD_ALLOWED_USERS=123456789
DISCORD_ALLOWED_ROLES=admin,engineers

This allows the specific user OR anyone with the admin/engineers roles.

Why restrict access? Cost: every query to Hermes consumes API credits (Claude, GPT-4, etc.). Unrestricted access equals token burn. Context bleed: if the bot runs in a shared channel, it accumulates conversation history across everyone. Restricting to a team keeps context clean.

Access controls apply at the user level, not the channel level. If user 123456789 is on the allowlist, they can DM the bot or mention it in any channel. If they're not on the allowlist, they can't trigger the bot anywhere. If you want the bot to only listen in certain channels, set DISCORD_CHANNELS to a comma-separated list of channel IDs:

DISCORD_CHANNELS=987654321,555666777

Now the bot ignores all other channels.

Step 5: Connect Hermes to Discord (The hermes gateway setup Command)

Assuming you've installed Hermes locally or on a VPS, open a terminal and run:

hermes gateway setup

The wizard will ask: What gateway do you want to set up? Select "Discord" from the list. Discord bot token? Paste your token (from Step 3). Your Discord user ID? Your own Discord user ID (used for admin commands and logging). Find it the same way: Developer Mode > right-click name > Copy User ID. Intents? Select MESSAGE_CONTENT, GUILD_MEMBERS, GUILDS, GUILD_MESSAGES, DIRECT_MESSAGES (defaults are fine; just confirm). Access control? Select allowlist (user, role, or all) and paste user IDs or role names.

The wizard creates a .env file with these settings:

DISCORD_TOKEN=your-token
DISCORD_USER_ID=your-id
DISCORD_INTENTS=MESSAGE_CONTENT,GUILD_MEMBERS,GUILDS,GUILD_MESSAGES,DIRECT_MESSAGES
DISCORD_ALLOWED_USERS=123,456

If you prefer to edit .env by hand instead, copy this template:

DISCORD_TOKEN=<bot-token>
DISCORD_USER_ID=<your-user-id>
DISCORD_INTENTS=MESSAGE_CONTENT,GUILD_MEMBERS,GUILDS,GUILD_MESSAGES,DIRECT_MESSAGES
DISCORD_ALLOW_ALL_USERS=false
DISCORD_ALLOWED_USERS=123456789,987654321

Once configured, start the gateway:

hermes gateway start

You should see output like: [INFO] Discord gateway initialized, [INFO] Connected to Discord as BotName#1234, [INFO] Ready to receive messages. If you see errors, move to the Troubleshooting section.

Step 6: Verify End-to-End in a Test Channel

Before you trust the bot in production, test it in a private channel:

1. Create a test channel (or use an existing private one). Invite your bot and yourself.
2. Check basic connectivity: mention the bot with @MyHermesAgent hello. Wait 5 seconds. The bot should respond. If nothing happens, move to Troubleshooting.
3. If the bot responds: try a more complex query like @MyHermesAgent what is 15 * 23?. The bot should calculate and reply. Try requesting a file: @MyHermesAgent write me a python function that reverses a string. The bot should generate code.
4. Test access control: ask a user who is NOT on the allowlist to mention the bot in the same channel. The bot should ignore them (no response). If it responds, your access policy is not working; check the DISCORD_ALLOWED_USERS variable.
5. Test in different contexts: DM the bot directly (should respond), mention it in a thread (should respond in the thread), mention it in a forum channel (should respond).
6. Verify message history: ask the bot @MyHermesAgent what did I just ask you?. The bot should reference the previous message. This confirms MESSAGE_CONTENT intent is working.

If all tests pass, the bot is ready for production channels.

Troubleshooting: Bot Online but Not Responding?

The bot appears in Discord (green online status) but doesn't reply to mentions. Here's the layered checklist:

Layer 1: Check Discord Developer Portal Settings

Go to Bot section. Confirm Message Content Intent is ON (blue toggle). Confirm Server Members Intent is ON. Go to OAuth2 > URL Generator. Confirm "Send Messages" and "Read Messages/View Channels" are checked. If any are off, toggle them on, save, and restart the gateway.

Layer 2: Check Hermes Gateway Configuration

Run hermes gateway status to see whether the gateway is running and connected. If it says "Disconnected" or "Not running", run hermes gateway restart. Wait 10 seconds and try mentioning the bot again.

Layer 3: Verify Intents in.env

Open your .env file and confirm: DISCORD_INTENTS=MESSAGE_CONTENT,GUILD_MEMBERS,GUILDS,GUILD_MESSAGES,DIRECT_MESSAGES. All five intents must be present. If MESSAGE_CONTENT is missing, the bot can't read message text. If you added it but the bot still doesn't work, restart the gateway again. The gateway loads intents on startup.

Layer 4: Check Access Control

If you have DISCORD_ALLOWED_USERS set, verify the user mentioning the bot is in the list (by Discord user ID, not display name). If using DISCORD_ALLOWED_ROLES, the user has that role in Discord. Test with DISCORD_ALLOW_ALL_USERS=true temporarily to rule out access control as the problem. If the bot responds to all users, access control was the issue.

Layer 5: Check Provider Credentials (API Keys)

Hermes needs API keys for the LLM (Claude, GPT-4, etc.). If intents, permissions, and gateway are all correct but the bot still doesn't respond, run hermes model list. This shows which LLM is configured. Verify your API key for that provider: for Claude (Anthropic), check ANTHROPIC_API_KEY; for GPT-4 (OpenAI), check OPENAI_API_KEY. If the key is missing or invalid, queries fail silently. Add or fix the key and restart the gateway.

Layer 6: Check Gateway Logs

Run hermes gateway logs to see real-time errors. Common errors: "Invalid token" means regenerate the bot token in Developer Portal; "Missing intents" means add intents to .env; "Unauthorized" means check channel permissions (the bot needs Send Messages in that channel).

Self-Hosted vs. Managed: Which Should You Choose?

If you're running Hermes yourself, you own the gateway process, restarts, monitoring, and uptime. A VPS costs $5-$65/month depending on traffic. API costs (Claude, GPT-4) depend on usage; typical teams spend $20-$200/month.

If you use managed Hermes on Opsily, you pay a fixed hosting fee and skip the ops. The platform manages gateway uptime, scaling, monitoring, and credentials. This costs $99-$499/month depending on tier, but it's fixed, predictable, and includes SLA uptime guarantees.

Choose self-hosted if you're experimenting, control your infra, or want zero recurring costs. Choose managed if you need 99.9% uptime SLA, your team is non-technical, you want support on call, or you want to ignore infrastructure entirely.

Frequently Asked Questions

Can Hermes Agents use Discord?

Yes. Hermes Agent connects to Discord via a gateway process. The bot receives messages, passes them to Hermes (which handles tools, memory, reasoning), and replies in real time. Hermes respects Discord's permission model and context (DMs, channels, threads).

How to get Hermes agent for free?

Hermes Agent itself is open-source (MIT license, 259,600 stars on GitHub, maintained by Nous Research). You can self-host it on any VPS or local machine. The LLM API costs are separate (Claude, GPT-4, etc. are paid). Some free tier LLMs exist (Llama via Ollama), but they're slow and not recommended for production.

How to talk with Hermes agent?

Multiple ways: CLI (hermes command), Discord/Telegram/Slack (via gateway), Web UI, mobile app. For Discord specifically: invite the bot to your server, configure the token, then mention the bot in channels or DM it directly. The bot will respond if you're on the allowlist.

How to configure Hermes with Discord?

Create a Discord app in Developer Portal, enable Message Content Intent and Server Members Intent, copy bot token, run hermes gateway setup, choose Discord, paste token and user ID, select intents and access control, run hermes gateway start, then verify in a test channel by mentioning the bot.

What are the terminal commands for Hermes Agent?

Main commands: hermes (start CLI), hermes gateway setup/start/restart/status, hermes model list/set, /skip (skip current response), /retry (redo last query), /new (start fresh session), /compress (compress memory). In Discord, type tool names as slash commands: /web_search, /write_file, etc.

Do Discord bots make money?

Not directly. Discord bots don't generate revenue. But Hermes can automate tasks that save your team time or money: report generation, code debugging, content creation, customer support triage. Those time savings have business value, even if the bot itself doesn't earn.

The Bottom Line

Connecting Hermes Agent to Discord is straightforward: create a bot in Developer Portal, enable Message Content Intent (the most common mistake), copy the token, configure access control, run hermes gateway setup, and test in a private channel. The troubleshooting checklist--intents, permissions, gateway status, access control, API keys--covers 95% of "bot online but not responding" issues. If you want a production setup with guaranteed uptime and no ops burden, Opsily's managed Hermes hosting handles gateway orchestration, scaling, monitoring, and SLA uptime for you.