Guides
How to connect Hermes Agent to Telegram
Telegram is the quickest way to turn a working Hermes Agent installation into something you can reach from your phone. The important word is working: Telegram is only an interface. If the model, provider or base installation is broken, the bot will be silent too.
This guide takes the shortest secure path: one private bot, one allowed Telegram user, a foreground test, then a background service. The official Telegram documentation goes much deeper into groups, voice, webhooks and private-chat topics; start here before adding those layers.
Before you touch Telegram
Confirm Hermes can complete a normal chat:
hermes doctor
hermes chat -q "Reply with exactly: Hermes is working"Fix either command before continuing. If Hermes is not installed yet, use the platform download and installation guide. If the first chat returns an HTTP 400, fix the provider or model identifier before debugging Telegram.
The host must also stay awake. A laptop is fine for testing, but a bot expected to answer around the clock belongs on an always-on machine. A small Hermes Agent VPS is enough when the model runs through a hosted provider.
Step 1 — create the bot in BotFather
Open Telegram and start a chat with @BotFather, Telegram’s official bot-management account. Check the handle carefully before sending anything.
- Send
/newbot. - Choose the display name users will see.
- Choose a unique username ending in
bot, such asmy_hermes_agent_bot. - Copy the token BotFather returns.
The token looks roughly like this:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZTreat it like a password. Do not paste a real token into a screenshot, issue,
public config file or support chat. Anyone who has it can operate the bot. If it
leaks, send /revoke to BotFather and configure Hermes with the replacement.
BotFather also offers /setdescription, /setabouttext and /setuserpic. These
are optional and do not affect the connection.
Step 2 — get your numeric Telegram user ID
Hermes restricts who can use the bot by numeric Telegram ID. Your @username is
not the ID and will not work in the allowlist.
The official Hermes guide recommends messaging
@userinfobot and copying the number it returns. It
should look like 123456789, with no @ prefix.
Using an allowlist matters because Hermes can access tools, files and a shell on its host. A publicly reachable bot with unrestricted access is not a harmless chatbot.
Step 3 — configure the Telegram gateway
Run the interactive setup:
hermes gateway setupSelect Telegram, then provide:
- the bot token from BotFather;
- your numeric Telegram user ID;
- any optional display settings you actually want.
The wizard writes the configuration for you. This is safer than hand-editing two different config files and is the route recommended by Nous Research.
If you deliberately need manual configuration, the essential values live in
~/.hermes/.env:
TELEGRAM_BOT_TOKEN=123456789:replace_with_your_real_token
TELEGRAM_ALLOWED_USERS=123456789For several users, enter comma-separated numeric IDs. Never commit this file to Git.
Step 4 — test it in the foreground
Do not install a service until the connection works interactively:
hermes gatewayLeave that terminal open, find your new bot in Telegram and send a private message.
If it replies, the token, allowlist, provider and gateway are all working together.
Press Ctrl+C after the test.
Telegram uses long polling by default: Hermes makes outbound connections to Telegram. You do not need to expose port 8080, forward a router port or make a VPS service publicly reachable for this normal setup.
Step 5 — keep the bot running
Install the supported background service:
hermes gateway install
hermes gateway start
hermes gateway statusOn Linux, the default is a user service. If the server must start the gateway at boot without that user logging in, the current Hermes CLI also supports a system-level service:
sudo hermes gateway install --systemUse one service method, not both. On a server already using the systemd unit from our Linux installation guide, keep that existing unit instead of creating a duplicate gateway process.
If the Telegram bot stays silent
Work through these checks in order.
1. Confirm the gateway is actually running
hermes gateway status
tail -50 ~/.hermes/logs/gateway.logIf the log reports an invalid token, return to BotFather, copy the current token
without spaces and run hermes gateway setup again.
2. Confirm the allowed user is a number
An entry such as @alice is wrong. The allowlist needs the numeric ID returned by
the ID bot. Re-run the wizard and replace it.
By default Hermes denies users who are not authorized. That is expected security behaviour, not a Telegram outage.
3. Confirm the CLI still answers
hermes chat -q "hello"If this fails, Telegram is not the cause. Run hermes doctor and fix the provider
or model configuration first.
4. Repair missing messaging dependencies
If the gateway itself reports missing Python packages:
cd ~/.hermes/hermes-agent
uv pip install -e ".[messaging]"Then restart it:
hermes gateway restart5. Make sure the token is not used twice
One Telegram bot token cannot be polled by two running Hermes gateways. This often happens after creating a second Hermes profile or leaving an old gateway service running. Stop the duplicate process or create a separate BotFather token for each profile.
Using Hermes in a Telegram group
Private messages are the cleanest first test. Groups add two independent filters: Telegram privacy mode controls which messages reach the bot, and the Hermes allowlist controls which senders may trigger it.
With BotFather privacy mode enabled, a bot normally sees commands, replies to its messages and direct mentions—not every line in the group. That is often the right default. If you change privacy mode in BotFather, remove the bot from the group and add it again so Telegram applies the new setting.
To keep Hermes quiet unless somebody addresses it, add this to
~/.hermes/config.yaml:
telegram:
require_mention: trueThen restart the gateway. Even in groups, keep TELEGRAM_ALLOWED_USERS restricted
to people who should be able to invoke an agent with tool access.
A secure default to keep
For a personal bot, the sensible baseline is:
- one unique bot token;
- your numeric ID as the only allowed user;
- long polling, with no inbound firewall port;
- the gateway running as a service on an always-on host;
- tool permissions no broader than you need;
- the token stored only in Hermes’s private environment file.
Once that works reliably, add groups, voice messages, cron delivery or Telegram topics one feature at a time. The bot is much easier to debug when every new layer starts from a known working connection.
FAQ
Does Hermes Agent need a public port for Telegram?
No, not with the default long-polling connection. The gateway makes outbound requests to Telegram, so a local machine or VPS does not need a Telegram port exposed. Webhook mode is a separate option for cloud platforms that sleep when idle.
Why does my Hermes Telegram bot not reply?
First confirm the CLI can answer, then check hermes gateway status and the last lines of ~/.hermes/logs/gateway.log. The usual causes are an invalid bot token, the wrong numeric user ID, a missing allowlist entry, or a gateway process that stopped.
Can I use a Telegram username in the Hermes allowlist?
No. Use the permanent numeric Telegram user ID, not the changeable @username.
Can several people use the same Hermes Telegram bot?
Yes. Add each person's numeric ID to the allowlist. Each user receives a separate conversation session, while the same Hermes installation and its configured tools serve the bot.
Does the bot keep working after I close SSH or my laptop?
Only if the gateway runs as a background service and the host remains awake. A sleeping laptop cannot answer Telegram messages; an always-on server is the more reliable host.