How to connect Hermes Agent to Telegram
You can use Telegram to remotely control your self-hosted Hermes Agent from any device. Access is handled through a dedicated bot and restricted to specific Telegram user IDs. To keep Hermes available around the clock, you can run the gateway on a Linux server or VPS.
Key Takeaways
- The messaging gateway connects your self-hosted Hermes Agent to Telegram, which only serves as the interface.
- Create a bot with BotFather and copy its secret bot token.
- Find your numeric Telegram user ID and authorise it as the allowed user.
- Configure the gateway with
hermes gateway setupand test it withhermes gateway run. - Install the gateway as a background service;
hermes doctorhelps if the bot doesn’t respond. - For 24/7 availability, run Hermes on a Linux server or VPS. A public server port is normally not required.
How do you connect Hermes Agent to Telegram?
The Hermes Agent messaging gateway is the native interface that connects the self-hosted autonomous Hermes Agent to external chat platforms like Telegram. It receives messages, assigns them to a session, passes them to the agent and sends the agent’s replies back to the relevant Telegram chat.
This lets you interact with Hermes Agent through the Telegram app on your smartphone, tablet or another computer. The AI agent itself continues to run on your own computer or server. Telegram simply provides the interface you use to send messages to the agent and receive its replies.
To set it up, you need three main components: a Telegram bot, a secret bot token and your personal Telegram user ID added to the list of allowed users. You then start the Hermes messaging gateway and, if needed, configure it as a persistent background service on a Linux server.
What do you need to connect Hermes Agent to Telegram?
Before you get started, Hermes Agent should already be installed and working properly. To check, open a terminal and start Hermes without Telegram:
hermesbashAsk a simple question and make sure the agent responds.
You’ll also need:
- a Telegram account,
- access to the terminal on the computer where Hermes is running,
- a model provider that has already been configured,
- an internet connection on the Hermes system.
How to create a Telegram bot with BotFather
A Telegram bot is a special Telegram account controlled by software rather than a person. To create one, use Telegram’s official management bot @BotFather. Open Telegram and search for @BotFather. Make sure to select the official BotFather account, then send the following command:
/newbottextBotFather will guide you through the setup process.
- Set a display name: BotFather first asks you to choose a name for the bot. This is the name that will appear later in the Telegram chat. It does not have to be unique and can be changed later.
- Choose a unique username: Next, choose a unique Telegram username for the bot. It must end in ‘bot’, for example, ‘my_hermes_agent_bot’. If the username you want is already taken, you’ll need to choose another one.
- Copy the bot token: Once the bot has been created, BotFather provides an API token. This token identifies Hermes to Telegram as the system operating the bot, so it works much like a password.
Do not publish the token or include it in screenshots, public documents, forum posts, or publicly accessible Git repositories. Anyone who knows the token can control the bot through the Telegram Bot API. If the token is accidentally exposed, you can use the /revoke command in BotFather to invalidate it and generate a new one.
How to find your Telegram user ID
In addition to the token, Hermes needs your personal Telegram user ID. This is a fixed numeric identifier and is different from your visible Telegram name or username. Unlike your username, which can be changed, your numeric user ID is what Hermes uses to control access.
Open @userinfobot in Telegram and start a chat or send the bot a message. The bot will respond with information about your account. Copy the value shown as your user ID.
What Telegram details does Hermes need?
| Configuration detail | What it contains | How to get it |
|---|---|---|
TELEGRAM_BOT_TOKEN |
Secret API token for your Telegram bot | @BotFather sends it after you create the bot with /newbot |
TELEGRAM_ALLOWED_USERS |
Your numeric Telegram user ID | Send @userinfobot a message to get your user ID |
| Bot username | Publicly visible username of the bot that ends in ‘bot’ | Choose it when creating the bot with @BotFather |
If you’re the only person using Hermes, just enter your own user ID. To give other people access later, add their IDs separated by commas.
How to configure the Hermes Agent gateway from the CLI
Hermes includes an interactive setup wizard that guides you through the Telegram configuration step by step in the CLI. Open a terminal on the computer where Hermes Agent is installed and enter the following command:
hermes gateway setupbashThe setup wizard will show you the supported messaging platforms. Use the arrow keys to select Telegram, and press Enter to confirm. Then enter the following details:
- the messaging platform,
- your Telegram bot token,
- the Telegram user IDs you want to authorise.
For the bot token, enter the value you received from BotFather. When asked which user IDs to authorise, enter the numeric Telegram user ID you found earlier. The setup wizard will save these details in the Hermes configuration. The bot token links Hermes to the Telegram bot you created.
Why is the user ID an important security safeguard?
Depending on how it is configured, Hermes Agent can access files, run programs, execute terminal commands, and use other tools. This means a publicly accessible bot would pose significantly more risk than a standard FAQ chatbot. Hermes uses a default-deny approach for the messaging gateway. If neither an allowlist nor explicit access for all users has been configured, unknown users cannot send requests to the agent for execution. A Telegram account can interact with Hermes only after its user ID has been authorised. For a bot used exclusively by you, a fixed allowlist of user IDs is the simplest and most transparent way to restrict access.
Do not rely on the default-deny approach alone. As a test, send the bot a message from a Telegram account that has not been authorised. Hermes should reject the request.
In particular, avoid enabling GATEWAY_ALLOW_ALL_USERS=true. This setting deliberately removes the global access restriction. If Hermes Agent has access to the system and terminal, this setting should only be used in highly controlled environments.
How to give multiple people access
If several trusted people need access to the same bot, enter their Telegram user IDs separated by commas:
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555bashBy default, everyone on the list has access to the same agent and the tools enabled for it. This means you should only add a user ID if that person is meant to have access to the system. Hermes keeps conversations in separate sessions, but the underlying agent capabilities remain available to all authorised users.
How to activate the Telegram gateway and test the connection
After configuring the gateway, first run it directly in the terminal to test the connection:
hermes gateway runbashThe gateway process will now run in the foreground, so you can see status and error messages directly in the terminal. Keep the terminal window open during the test. If the connection is successful, you should see a message confirming that the Telegram adapter is connected. Then open the bot you created in Telegram and send it a message.
Run the following tests in order:
- Check the session status: Send
/status. Hermes should show information about the current session. - Send a regular message: Ask your agent something like: ‘Which system tools can you currently use? Just list their names and don’t run any of them yet’. This checks whether a regular message is sent to Hermes, processed by the agent and returned to Telegram as a response.
- Start a new conversation: Send
/newto start a fresh session without the previous conversation context. If the bot responds to all three tests, two-way communication is working.
When you’re finished testing, press Ctrl+C in the terminal to stop the gateway.
How to install the gateway as a background service
To run the gateway without having to keep a terminal window open, install it as a background service:
hermes gateway installbashOnce installed, you can start, stop and check the service with the following commands:
hermes gateway start
hermes gateway stop
hermes gateway statusbashAfter making changes to the Telegram configuration, restart the gateway:
hermes gateway stop
hermes gateway startbashAlternatively, you can restart it directly with:
hermes gateway restartbashhermes gateway start starts the background service you installed earlier. If you haven’t installed the service yet, run hermes gateway install first. By contrast, hermes gateway run starts the gateway in the foreground so you can see its output directly in the terminal.
Then check the status:
hermes gateway statusbashFinally, send another message to the Telegram bot. It should now respond even when no Hermes terminal window is open.
What to do if the bot doesn’t respond
As a first troubleshooting step, run:
hermes doctorbashHermes will check the installation, key configuration settings, and required dependencies, among other things. Any problems it finds will be displayed in the terminal along with possible solutions. Hermes can also try to fix some issues automatically:
hermes doctor --fixbashNext, check whether the gateway is running. If the bot still doesn’t respond, go through the setup manually:
- Is the bot token complete, with no extra spaces?
- Is the numeric user ID correct?
- Did you enter the user ID rather than the Telegram username?
- Is the gateway running according to
hermes gateway status? - Does Hermes work directly in the terminal without Telegram?
- Does the computer have an active internet connection?
To see connection errors, stop the background service and run the gateway in the foreground again:
hermes gateway stop
hermes gateway runbashAny connection errors will then appear directly in the terminal.
How to run Hermes Agent with Telegram 24/7
If Hermes is running on your laptop or desktop computer, the Telegram bot will only be available while the computer is turned on, connected to the internet and the gateway is running. If the computer is shut down or goes to sleep, Hermes can no longer process Telegram messages.
For 24/7 availability, run Hermes on a Linux server or Virtual Private Server (VPS) instead. A VPS is a virtual computer hosted in a data centre that stays up and running around the clock. You access its terminal through an encrypted SSH connection.
How to move Hermes to a Linux server or VPS
Start by installing Hermes on the Linux server and setting up the model provider. Then test Hermes with a regular chat to make sure it’s working properly. If it is, run the gateway setup wizard again:
hermes gateway setupbashYou can reuse the same Telegram bot token and authorised user ID. Before starting the bot on the server, however, stop the gateway on your local computer. This prevents both Hermes installations from trying to handle the same bot at the same time.
For a Linux server that stays up and running, set up a system-wide service that starts automatically when the server boots:
sudo hermes gateway install --system
sudo hermes gateway start --systembashYou can check the service status with:
sudo hermes gateway status --systembashTo view the latest log messages, run:
journalctl -u hermes-gateway -fbashWith systemd, the gateway runs in the background and can start again after the server reboots. Hermes uses a user-level service for workstations and a system-wide service for always-on, headless servers. On a VPS, avoid running Hermes with administrator privileges unless necessary. Where possible, use a dedicated Linux user without unrestricted root access.
How to run Hermes in Docker
Docker runs applications in isolated containers. This makes it easier to keep Hermes running around the clock while helping to prevent commands executed by the agent from running directly on the host system. Once Hermes has been configured, start the official Hermes container in the background as follows:
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway runbashThe --restart unless-stopped option restarts the container after a crash or server reboot unless you previously stopped it manually. The mounted ~/.hermes directory stores the configuration, sessions and credentials outside the temporary container.
Docker is not required to connect Hermes to Telegram. If you’re new to Hermes, the standard installation with the systemd service Hermes creates is usually the simpler option.
How to run the Telegram gateway securely on a server
You normally do not need to open a public port on the server to connect Hermes to Telegram. By default, the Hermes gateway uses long polling: Hermes establishes an outgoing connection to Telegram and regularly checks for new messages. This means Telegram does not need to connect directly to your server from the internet.
If you use Telegram as the only way to interact with Hermes, do not expose the internal Hermes API port to the internet. Opening additional ports can expose more services on the server to the internet and increase the attack surface.
What to check before running the gateway 24/7
Before leaving the gateway running continuously, check the following:
- Keep the Telegram bot token in the protected Hermes configuration and nowhere else.
- Only add the numeric user IDs of people who are explicitly authorised to
TELEGRAM_ALLOWED_USERS. - Make sure
GATEWAY_ALLOW_ALL_USERSis disabled. - Avoid running Hermes with root or administrator privileges unless necessary.
- Keep any server and API ports you do not need closed.
- Do not store credentials in public Git repositories or publicly accessible log files.
- Keep both the operating system and Hermes Agent up to date.
- Where possible, run tools with broad file or terminal access in an isolated environment.
For production environments, you can use an isolated terminal backend based on Docker. This means commands run by the agent are executed inside a container rather than directly on the host server. This isolation does not replace the Telegram allowlist or the need to protect the bot token. Instead, it adds another layer of security.
Conclusion
To connect Hermes Agent to Telegram, you need a Telegram bot created with BotFather, its secret API token and your numeric Telegram user ID. The hermes gateway setup command will guide you through the configuration and use your user ID to restrict access.
After testing the connection, you can install the gateway as a background service and leave it running. If Hermes runs on a Linux server or VPS, this keeps the agent accessible even when your own computer is switched off. To keep the setup secure, keep the bot token private, allow access only for authorised user IDs and isolate the agent’s system tools from the host server wherever possible.