Hermes Agent can run inside Discord as a real bot, not a stateless webhook. A Discord message enters the Hermes messaging gateway, passes authorization and routing checks, loads the right session history, runs the normal Hermes agent loop with tools and memory, then sends the answer back to Discord.
That makes Discord a strong control room for a private AI operator. It also means the setup deserves a tight boundary: one bot, known users or roles, explicit channels, no committed secrets, and a quick test that proves the gateway is actually reading messages.
This guide is a simplified companion to the official Hermes Agent Discord docs. Use the official docs as the source of truth, then use this page as the field checklist when you want the shortest path from “new Discord bot” to “Hermes answers in my private channel.”
Build an agent that keeps working after you close your laptop.
Start with the free setup checklist. It helps you avoid the usual traps: no place for state, secrets mixed with prompts, automations that send before you approve them, and logs you cannot debug later.
- VPS, Codex, Hermes, and Discord setup steps
- Approval gates before email, tickets, or posts change
- Reusable skills, scripts, and operating checklists
- A preorder path if you want the full walkthrough
What Discord + Hermes connects
A working Hermes Discord setup connects four pieces:
Hermes on Discord is not just an incoming webhook. The official Discord docs describe the gateway pipeline as authorization, mention or free-response checks, session lookup, transcript loading, normal Hermes execution, and response delivery.
That distinction matters. You are not making a random bot that forwards prompts. You are giving a Discord surface access to your configured Hermes runtime.
Who this setup is for
Use this setup if you want:
- a private Discord channel where an operator can ask Hermes for help;
- a DM bot for one-person command-center work;
- a team channel where only allowed users or roles can trigger the agent;
- cron output, reminders, or workflow alerts delivered into Discord;
- a practical control room before adding X, GitHub, Google Workspace, email, or CRM workflows.
Do not start here if the VPS or Hermes runtime is still unclear. First make sure Hermes works locally and that secrets, logs, and state live somewhere predictable. The related BuildLeanSaaS foundation guides are linked near the bottom.
Prerequisites
Before touching the Discord Developer Portal, have these ready:
| Requirement | Why it matters |
|---|---|
| Hermes Agent installed | The Discord bot talks to the Hermes gateway. |
| A Discord account with Developer Portal access | You need to create an application and bot. |
| Manage Server permission | Required to invite the bot to a server. |
| Discord Developer Mode enabled | Required to copy user, channel, and server IDs. |
| A private server, channel, or DM plan | Keeps the first setup narrow and easy to debug. |
| A safe place for secrets | The bot token must not be committed or pasted into public docs. |
If you only need a personal operator, start with a DM. If you need a visible team workflow, create one private server channel first.
Step 1: Create the Discord application and bot
In Discord’s Developer Portal:
- Open https://discord.com/developers/applications.
- Click New Application.
- Name it something obvious, for example
Hermes Agent. - Open Bot in the sidebar.
- Leave Require OAuth2 Code Grant off.
- Keep Public Bot on if you want Discord’s generated install link. If you turn Public Bot off, use a manual invite URL instead.
Copy the Application ID from the General Information page. You need it if you build the invite URL manually.
Step 2: Enable the required gateway intents
This is the most common failure point.
On the bot page, enable these privileged gateway intents:
| Intent | Required? | Why |
|---|---|---|
| Server Members Intent | Yes | Lets Hermes resolve members and role-based access. |
| Message Content Intent | Yes | Lets Hermes read the text people send. |
| Presence Intent | No | Not needed for the basic setup. |
If the bot comes online but never responds, check Message Content Intent first. Without it, Discord can deliver message events while hiding the actual message text.
Step 3: Invite the bot to your server
Use either Discord’s Installation tab or a manual OAuth URL.
Recommended scopes:
Recommended permission integer from the official docs:
Manual invite URL shape:
Replace YOUR_APP_ID with the Application ID from Step 1.
The recommended permissions include the practical bot basics: view channels, send messages, embed links, attach files, read message history, send in threads, and add reactions. For a first build, invite the bot only where it needs to operate.
Step 4: Copy your Discord IDs
Hermes uses Discord IDs for authorization and routing.
Turn on Developer Mode in Discord:
- Open User Settings.
- Go to Advanced.
- Enable Developer Mode.
- Right-click your user, server, channel, role, or thread.
- Click Copy ID.
At minimum, copy your own Discord user ID. For server workflows, also copy the channel ID where Hermes should respond or receive proactive messages.
Step 5: Configure Hermes Agent
The official docs recommend the interactive gateway setup for most users:
Choose Discord, then paste the bot token and your allowed Discord user ID when prompted.
For manual configuration, keep credentials in ~/.hermes/.env:
Use comma-separated IDs for multiple users:
If your access model is role-based, use role IDs instead:
Do not put real bot tokens in GitHub issues, docs, screenshots, public repos, or Discord messages. Use [REDACTED] in examples.
Step 6: Pick the channel behavior you actually want
Hermes can behave differently in DMs, normal channels, free-response channels, and threads.
| Surface | Default behavior |
|---|---|
| DMs | Hermes responds to every message. No mention needed. |
| Server channels | Hermes responds only when directly mentioned. |
| Free-response channels | Hermes answers inline without mentions. |
| Threads | Hermes replies in the same thread. |
| Shared channels | Session history is isolated per user by default. |
For one private command channel where you do not want to mention the bot every time, set a free-response channel in ~/.hermes/config.yaml:
For a busier server, keep the default mention-required behavior. That prevents the bot from jumping into conversations that were not meant for it.
Hermes also isolates shared channel sessions per user by default:
Only set this to false if you intentionally want one shared room transcript. Shared room sessions can grow context faster and one person’s long tool-heavy run can affect the whole room.
Step 7: Start and verify the gateway
Start Hermes gateway in the foreground first:
If your local Hermes version uses the shorter alias, this also works:
Now test the actual Discord surface:
- Wait for the bot to show online.
- DM the bot, or mention it in the allowed server channel.
- Send a tiny test message:
status check. - Confirm Hermes responds in the expected place.
- If you configured a free-response channel, send a second message without an
@mention.
Then check gateway health:
For a long-running server, install or run the gateway as a managed service only after the foreground test works:
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Bot is online but never replies | Message Content Intent is disabled | Enable Message Content Intent in Developer Portal, then save changes. |
| User gets ignored | User is not authorized | Add their ID to DISCORD_ALLOWED_USERS or add an allowed role. |
| Bot replies only when mentioned | Default server-channel behavior | Add the channel to DISCORD_FREE_RESPONSE_CHANNELS or discord.free_response_channels. |
| Bot responds in places it should not | Channel scope is too broad | Use DISCORD_ALLOWED_CHANNELS or DISCORD_IGNORED_CHANNELS. |
| Threads feel noisy with multiple bots | Thread mention shortcut is too permissive | Set discord.thread_require_mention: true. |
| Cron output goes nowhere useful | No home channel configured | Set DISCORD_HOME_CHANNEL to the target channel ID. |
| One user interrupts another | Room is using shared sessions | Keep group_sessions_per_user: true unless shared context is intentional. |
Security boundary notes
A safe first Discord setup is intentionally boring:
- Allow only known users or roles.
- Start with one private channel or DMs.
- Keep real tokens in
~/.hermes/.env, never in content or source code. - Use
DISCORD_ALLOWED_CHANNELSwhen the bot should operate only in specific rooms. - Use
DISCORD_IGNORED_CHANNELSfor rooms where it should never answer. - Keep
DISCORD_ALLOW_MENTION_EVERYONE=falseandDISCORD_ALLOW_MENTION_ROLES=falseunless you intentionally need broad pings. - Do not treat Discord as a public shell.
- Do not expose a raw Hermes control endpoint just because Discord is working.
For business workflows, the useful pattern is observe, summarize, draft, approve. Let Hermes reduce repeated operator work, but keep meaningful side effects reviewable.
Related BuildLeanSaaS pages
Use these next if you are building the full Always-On Agents control room:
- Hermes Discord Control Channel
- Connect Hermes to Discord
- Prepare a VPS for Hermes
- Install Hermes/OpenClaw: A Private AI Agent Runtime on Your VPS
- Discord Automation Bot: A Safe Control Room for Hermes AI Workflows
- Connect Hermes to Google Workspace
Official docs used
This page is a companion guide. The official Hermes Agent docs remain the canonical reference:
- Hermes Agent docs
- Messaging gateway docs
- Discord setup docs
- Configuration docs
- CLI command reference
- Full llms.txt docs bundle
Build an agent that keeps working after you close your laptop.
Start with the free setup checklist. It helps you avoid the usual traps: no place for state, secrets mixed with prompts, automations that send before you approve them, and logs you cannot debug later.
- VPS, Codex, Hermes, and Discord setup steps
- Approval gates before email, tickets, or posts change
- Reusable skills, scripts, and operating checklists
- A preorder path if you want the full walkthrough