A Hermes Agent bot is your Hermes Agent running inside a chat app such as Telegram, Discord, Slack or WhatsApp, so you can message it from your phone like a teammate.
The part of Hermes that makes this work is called the messaging gateway, and it's built into the free, open-source agent from Nous Research.
You don't install a separate product to get a bot, because the same agent with the same tools, memory and skills simply answers in a different place.
This is the operator walkthrough, so I checked every command below against the official Hermes docs and against hermes gateway --help on my own install, which is version 0.21.4.
I run most of my Hermes work through the Bots tab in my Agent OS, so the Telegram steps here come from the official docs and the CLI help rather than from one of my videos.
What A Hermes Agent Bot Actually Is
Hermes Agent is a free AI agent that can run commands, use tools, remember things and work on a schedule.
Most people first meet it in a terminal or in the desktop app.
A Hermes Agent bot is that same agent with a chat app as its front door.
The official docs describe the gateway as a single background process that connects to all your configured platforms, handles sessions, runs cron jobs and delivers voice messages.
That one sentence explains why the bot feels different from a normal chatbot.
It isn't a script that replies with canned text, because every message goes through the full agent with its tools and memory.
Hermes Agent is released under the MIT licence, so the software costs nothing.
The model you plug into it is the only part that can send you a bill, and I cover that in the cost section below.
Which Platforms A Hermes Agent Bot Runs On
The messaging page in the official docs lists more platforms than most people expect.
It names Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles for iMessage, QQ, Yuanbao, Microsoft Teams, LINE, ntfy and your browser.
The features differ per platform, and the docs publish a comparison table.
Here are the rows that matter for most operators, copied from that table.
| Platform | Voice | Images | Files | Threads | Streaming replies |
|---|---|---|---|---|---|
| Telegram | Yes | Yes | Yes | Yes | Yes |
| Discord | Yes | Yes | Yes | Yes | Yes |
| Slack | Yes | Yes | Yes | Yes | Yes |
| WhatsApp (built-in bridge) | No | Yes | Yes | No | Yes |
| Signal | No | Yes | Yes | No | No |
| No | Yes | Yes | Yes | No | |
| Matrix | Yes | Yes | Yes | Yes | Yes |
Each platform connects in its own way, and the docs are honest about the trade-offs.
- Telegram uses a bot token from BotFather, and it is the simplest route.
- Discord runs as a bot that answers in direct messages or server channels.
- Slack uses Socket Mode, so your machine doesn't need a public web address.
- WhatsApp uses a built-in bridge that emulates a WhatsApp Web session, and the docs warn that this unofficial route carries a small risk of account restrictions.
- Signal connects through the signal-cli daemon, which needs Java 17 or newer.
- Email uses standard IMAP and SMTP, and the docs tell you to give the agent its own dedicated mailbox.
- Matrix works with any homeserver and supports optional end-to-end encryption.
I'd start with Telegram, because it needs one token and no public server.
🔥 Want my exact Hermes Agent Bot setup, step by step? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
How To Create A Hermes Agent Bot On Telegram, Step By Step
You need Hermes installed first.
If you haven't done that, my one-click Hermes setup guide gets you to a working agent.
Step 1: Create the bot in BotFather
Open Telegram and search for @BotFather, which is Telegram's official bot management tool.
Send the command /newbot.
Choose a display name, which can be anything you like.
Choose a username, which has to be unique and has to end in "bot".
BotFather replies with an API token.
Step 2: Treat the token like a password
The docs put a warning on this step, and I agree with it.
Anyone who has the token can control your bot.
If the token leaks, you revoke it straight away with /revoke in BotFather.
Never paste it into a chat, a screenshot or a public repository.
Step 3: Find your numeric user ID
Hermes controls access with numeric Telegram user IDs, and your ID isn't your username.
Message @userinfobot on Telegram and it replies with your number.
Save that number, because you'll need it in the next step.
Step 4: Run the gateway wizard
This is the command that does the wiring.
hermes gateway setup
Select Telegram when it asks.
The wizard asks for your bot token and your allowed user IDs, then writes the configuration for you.
The docs say the wizard shows which platforms are already configured and offers to start or restart the gateway when you finish.
Step 5: Know the manual route
You can skip the wizard and add two lines to the .env file in your Hermes home folder.
TELEGRAM_BOT_TOKEN=your-token-here
TELEGRAM_ALLOWED_USERS=123456789
You can list several user IDs with commas between them.
There's also a no-terminal route.
The docs say the Messaging page in the dashboard and the desktop app has a "Create with QR" button for Telegram, which creates the bot, detects your user ID and restarts the gateway for you.
Step 6: Start the gateway and test it
Run the gateway in the foreground first, so you can see what happens.
hermes gateway
The docs say the bot should come online within seconds.
Send it a message on Telegram and wait for the reply.
Step 7: Install it as a service
A foreground gateway stops when you close the terminal, so the next step makes it permanent.
hermes gateway install
hermes gateway start
hermes gateway status
On Linux this installs a user service, and on a Mac it installs a launchd service.
On a VPS that should come back after a reboot, the docs give a system-level version.
sudo hermes gateway install --system
sudo hermes gateway start --system
The docs recommend the user service for laptops and the system service for headless servers.
The CLI help also says hermes gateway run is the recommended form for WSL and Docker.
Step 8: Set a home channel
Type /sethome in the chat where you want scheduled results to land.
The docs say cron jobs deliver their results to that home channel.
You can then schedule a job from the terminal and send it to Telegram.
hermes cron create "0 7 * * *" "Send me a short brief of today's priorities" --deliver telegram
The --deliver flag accepts targets such as telegram, discord and signal, according to the CLI help.
Step 9: Tidy the bot's profile
BotFather has optional commands that make the bot nicer to use.
You can set a description with /setdescription, upload an avatar with /setuserpic and define the command menu with /setcommands.
🔥 Want this bot set up with someone watching your screen? Inside the AI Profit Boardroom, there's a full Hermes Agent course plus four live coaching calls a week where you can share your screen and get your gateway fixed. You'll be building alongside 3,400+ members. → Get access here
How A Hermes Agent Bot Behaves In DMs And In Groups
A direct message is simple, because the bot answers every message from an allowed user.
Groups are where most setups go wrong, and the reason is a Telegram setting called privacy mode.
Telegram switches privacy mode on for every new bot.
With privacy mode on, the bot only sees messages that start with a slash command, replies to its own messages and service messages.
With privacy mode off, the bot receives every message in the group.
You turn it off by sending /mybots to BotFather, picking your bot and choosing Bot Settings, then Group Privacy, then Turn off.
The docs add one detail that catches people out.
You have to remove the bot from the group and add it again, because Telegram caches the privacy state when the bot joins.
Promoting the bot to group admin is the alternative, because admin bots always receive every message.
Your allowlist still applies inside a group, so only authorised users can trigger the bot.
If you don't want the bot replying to ordinary chatter, set telegram.require_mention: true in your config.
The bot then answers replies to its own messages, @mentions, commands addressed to it and any wake words you configure.
If you run several Hermes bots in one group, the docs say to create one bot token per profile and never reuse a token in two running gateways.
Discord behaves in a similar way out of the box.
The docs say Hermes responds to every direct message on Discord, and it only responds in server channels when you @mention it.
Approvals And Safety On A Hermes Agent Bot
A bot with terminal access is powerful, so the safe defaults matter.
The first layer is who can talk to it.
The docs say the gateway denies all users who aren't in an allowlist or paired through a direct message.
There is a setting that allows everyone, and the docs mark it as not recommended for bots with terminal access.
The second option is pairing, which saves you from collecting user IDs by hand.
An unknown user who messages the bot gets a one-time pairing code, and you approve it from your terminal.
hermes pairing approve telegram XKGH5N7P
hermes pairing list
hermes pairing revoke telegram 123456789
The docs say pairing codes expire after one hour and are rate-limited.
The second layer is what the agent is allowed to run.
Hermes checks every command against a list of dangerous patterns before it runs.
The default approval mode is called smart, which approves low-risk commands, denies clearly dangerous ones and asks you about the uncertain ones.
When it asks, you reply /approve or /deny in the chat.
Scheduled jobs are stricter, because the default for cron is to deny a dangerous command when nobody is there to approve it.
There's also a split between admins and regular users.
You can make yourself an admin and limit everyone else to the slash commands you choose, and /whoami shows each person which tier they're in.
The command I'd memorise is hermes pause.
The CLI help describes it as a global emergency stop that halts new work, including cron jobs and new gateway turns, until you run hermes resume.
🚀 Ready to put Hermes Agent Bot to work in your business? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
The Chat Commands Worth Knowing
Once the bot is live, you control it with slash commands inside the chat.
| Command | What it does |
|---|---|
/new |
It starts a fresh conversation. |
/model |
It shows or changes the model for that chat. |
/stop |
It stops the running agent. |
/status |
It shows session information. |
/usage |
It shows token usage for the session. |
/bg <prompt> |
It runs a prompt in a separate background session and reports back. |
/btw <question> |
It asks a side question without interrupting the current job. |
/sethome |
It sets the current chat as the home channel. |
/voice |
It controls voice replies. |
/help |
It lists the available commands. |
You can also type a slash followed by the name of any installed skill.
Sessions don't reset after a quiet period, so the bot keeps the context until you type /new.
Voice notes work on Telegram too.
The docs say voice messages are transcribed automatically, and the local option uses faster-whisper on your own machine with no API key.
What A Hermes Agent Bot Costs
There are three places a bot can cost money, and two of them can be zero.
| Layer | What it costs | How to keep it at zero |
|---|---|---|
| Hermes Agent | It is free under the MIT licence. | There is nothing to pay. |
| The chat platform | Creating a Telegram bot through BotFather is free. | Stay on bot-token platforms such as Telegram or Discord. |
| The model | It depends on the provider you choose. | Pick a model marked free on Nous Portal, or run a local model. |
| The machine | Your own computer adds no bill, and a server does. | Run it on a machine you already own. |
The docs add a tip that's worth repeating.
Bots need a model provider and also tool providers for things like speech and web search, and a Nous Portal subscription bundles them.
Free model lists rotate, so I never build a business process around one free model.
If you want the bot online when your laptop is shut, you need a server or a managed host.
My best Hermes Agent VPS breakdown covers the server choice, and my FlyHermes explainer covers one paid host that bundles the channels for you.
Gotchas I'd Check Before Trusting The Bot
The first gotcha is the laptop queue.
By default, the Telegram adapter drops messages that arrived while the gateway was offline when it cold boots.
That suits an always-on server, and it's wrong for a laptop that sleeps overnight.
The docs give a setting called drop_pending_on_cold_boot, which you set to false to receive the backlog on startup.
The second gotcha is one token in two places.
Telegram rejects two gateways polling the same bot token, so don't run the same bot from two machines.
The third gotcha is WhatsApp.
The built-in bridge isn't the official Business API, so the docs recommend a dedicated phone number rather than your personal one.
The fourth gotcha is polling on a sleeping cloud machine.
Hermes uses long polling by default, and the docs describe a webhook mode for cloud platforms that put idle machines to sleep.
The fifth gotcha is generated files in Docker.
Attachments are sent by the gateway process, so a file that only exists inside a container can't be delivered until you mount a shared folder.
Bot Mode And Hermes Bots Are Different Things
The word "bot" means three things around Hermes, so here's the map.
| Name | What it is | Where it lives |
|---|---|---|
| Hermes Agent bot | It is Hermes on a messaging platform through the gateway. | It lives in Telegram, Discord, Slack and the other chat apps. |
| Hermes Bot Mode | It is a desktop plugin from Nous Research that shows your profiles as a roster of named bots. | It lives in the Hermes desktop app. |
| Hermes Bots in my Agent OS | It is the same roster idea rebuilt as a Bots tab in my own dashboard. | It lives in the Agent OS I run every day. |
Bot Mode launched in August as a public beta plugin, and it's MIT licensed like Hermes itself.
Each bot gets its own chat, its own memory, its own routines and its own model if you pin one.
Bots can also message each other through something called the Agent Inbox.
The smart part is that a bot in Bot Mode is just a Hermes profile, so nothing new is bolted onto the core.
I cover that feature properly in my Hermes Agent Bot Mode walkthrough, and my Hermes Bot Mode guide has the screen recordings.
Inside my Agent OS, I create a bot with three boxes, which are a name, a title and a description.
In my latest Hermes video I also talk about creating a Hermes bot from an active profile, so a profile I already use for one model becomes a named bot on the roster.
The two worlds connect in a neat way.
The CLI help shows that a cron job can deliver to bot-chat followed by a profile name, which drops the result into that bot's own chat instead of Telegram.
🚀 Want the Bots roster already wired in? The AI Profit Boardroom includes my installable Agent OS, with the Hermes Bots tab, the profiles and the dashboard already connected. You also get four coaching calls a week and 3,400+ members to help when you're stuck. → Join the AI Profit Boardroom
Related Reading
- My Hermes Agent background guide explains how the gateway service, cron and background sessions keep working while you're away.
- The best Hermes Agent setup ranking shows where an always-on bot fits in a full stack.
- My Herald OS walkthrough covers a free desktop you can wrap around Hermes.
Also On Our Network
- 🌐 How a business or agency puts a Hermes bot to work
- 🌐 Every Hermes bot platform and feature, scored
- 🌐 The Hermes bot quick-start and how it fits an Agent OS
- 🌐 Which model to put behind a Hermes bot, with real bench scores
FAQ: Hermes Agent Bot
What is a Hermes Agent bot?
A Hermes Agent bot is Hermes Agent connected to a chat app through its built-in messaging gateway.
You message it on Telegram, Discord, Slack, WhatsApp or another supported platform, and the same agent answers with its normal tools, memory and skills.
How do I create a Hermes Telegram bot?
You message @BotFather, send /newbot and copy the token.
You get your numeric user ID from @userinfobot, then you run hermes gateway setup, choose Telegram and paste both in.
You run hermes gateway to test it and hermes gateway install to keep it running.
Is a Hermes Agent bot free?
Hermes Agent is free and open source under the MIT licence, and creating a Telegram bot through BotFather costs nothing.
The model behind the bot is the part that can cost money, and you can use a free model on Nous Portal or a local model.
Who can message my Hermes bot?
By default the gateway denies every user who isn't on an allowlist or paired through a direct message.
You add numeric user IDs to the allowlist, or you approve a one-time pairing code with hermes pairing approve.
Why does my Hermes bot work in DMs but not in a Telegram group?
Telegram bots have privacy mode switched on by default, so the bot only sees slash commands and replies to its own messages in a group.
You turn Group Privacy off in BotFather and re-add the bot, or you promote the bot to group admin.
Is a Hermes Agent bot the same as Hermes Bot Mode?
No, they're different features.
A Hermes Agent bot usually means Hermes on a messaging platform through the gateway.
Bot Mode is a desktop plugin that shows your Hermes profiles as a roster of named bots.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I built Goldie Agency, a 7-figure SEO and link building agency based in Bangkok.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote the book "Link Building Mastery".
- I run GoldieBench, where I score AI models on real one-shot builds.
→ Get my best AI training inside the AI Profit Boardroom
Create the token, lock the allowlist and install the service, and you'll have a working Hermes Agent bot.
