You can use Telegram to remotely control your self-hosted Hermes Agent from any device. Access is handled through a dedicated bot and re­strict­ed 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 authorize it as the allowed user.
  • Configure the gateway with hermes gateway setup and test it with hermes gateway run.
  • Install the gateway as a back­ground service; hermes doctor helps if the bot doesn’t respond.
  • For 24/7 avail­abil­i­ty, 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 au­tonomous 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 smart­phone, 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 com­po­nents: 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 per­sis­tent back­ground 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:

hermes
bash

Ask 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 con­fig­ured,
  • an internet con­nec­tion on the Hermes system.

How to create a Telegram bot with BotFather

A Telegram bot is a special Telegram account con­trolled by software rather than a person. To create one, use Telegram’s official man­age­ment bot @BotFather. Open Telegram and search for @BotFather. Make sure to select the official BotFather account, then send the following command:

/newbot
text

BotFather will guide you through the setup process.

  1. 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.
  2. 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.
  3. Copy the bot token: Once the bot has been created, BotFather provides an API token. This token iden­ti­fies Hermes to Telegram as the system operating the bot, so it works much like a password.
Note

Do not publish the token or include it in screen­shots, public documents, forum posts, or publicly ac­ces­si­ble Git repos­i­to­ries. Anyone who knows the token can control the bot through the Telegram Bot API. If the token is ac­ci­den­tal­ly exposed, you can use the /revoke command in BotFather to in­val­i­date 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 iden­ti­fi­er 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 @user­in­fobot in Telegram and start a chat or send the bot a message. The bot will respond with in­for­ma­tion about your account. Copy the value shown as your user ID.

What Telegram details does Hermes need?

Con­fig­u­ra­tion 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 @user­in­fobot 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 in­ter­ac­tive setup wizard that guides you through the Telegram con­fig­u­ra­tion step by step in the CLI. Open a terminal on the computer where Hermes Agent is installed and enter the following command:

hermes gateway setup
bash

The 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 authorize.

For the bot token, enter the value you received from BotFather. When asked which user IDs to authorize, enter the numeric Telegram user ID you found earlier. The setup wizard will save these details in the Hermes con­fig­u­ra­tion. 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 con­fig­ured, Hermes Agent can access files, run programs, execute terminal commands, and use other tools. This means a publicly ac­ces­si­ble bot would pose sig­nif­i­cant­ly 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 con­fig­ured, unknown users cannot send requests to the agent for execution. A Telegram account can interact with Hermes only after its user ID has been au­tho­rized. For a bot used ex­clu­sive­ly by you, a fixed allowlist of user IDs is the simplest and most trans­par­ent way to restrict access.

Note

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 au­tho­rized. Hermes should reject the request.

In par­tic­u­lar, avoid enabling GATEWAY_ALLOW_ALL_USERS=true. This setting de­lib­er­ate­ly removes the global access re­stric­tion. If Hermes Agent has access to the system and terminal, this setting should only be used in highly con­trolled en­vi­ron­ments.

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,555555555
bash

By 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 con­ver­sa­tions in separate sessions, but the un­der­ly­ing agent ca­pa­bil­i­ties remain available to all au­tho­rized users.

How to activate the Telegram gateway and test the con­nec­tion

After con­fig­ur­ing the gateway, first run it directly in the terminal to test the con­nec­tion:

hermes gateway run
bash

The gateway process will now run in the fore­ground, so you can see status and error messages directly in the terminal. Keep the terminal window open during the test. If the con­nec­tion is suc­cess­ful, you should see a message con­firm­ing 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:

  1. Check the session status: Send /status. Hermes should show in­for­ma­tion about the current session.
  2. 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.
  3. Start a new con­ver­sa­tion: Send /new to start a fresh session without the previous con­ver­sa­tion context. If the bot responds to all three tests, two-way com­mu­ni­ca­tion is working.

When you’re finished testing, press Ctrl+C in the terminal to stop the gateway.

How to install the gateway as a back­ground service

To run the gateway without having to keep a terminal window open, install it as a back­ground service:

hermes gateway install
bash

Once installed, you can start, stop and check the service with the following commands:

hermes gateway start
hermes gateway stop
hermes gateway status
bash

After making changes to the Telegram con­fig­u­ra­tion, restart the gateway:

hermes gateway stop
hermes gateway start
bash

Al­ter­na­tive­ly, you can restart it directly with:

hermes gateway restart
bash

hermes gateway start starts the back­ground 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 fore­ground so you can see its output directly in the terminal.

Then check the status:

hermes gateway status
bash

Finally, 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 trou­bleshoot­ing step, run:

hermes doctor
bash

Hermes will check the in­stal­la­tion, key con­fig­u­ra­tion settings, and required de­pen­den­cies, 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 au­to­mat­i­cal­ly:

hermes doctor --fix
bash

Next, 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 con­nec­tion?

To see con­nec­tion errors, stop the back­ground service and run the gateway in the fore­ground again:

hermes gateway stop
hermes gateway run
bash

Any con­nec­tion 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 avail­abil­i­ty, 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 con­nec­tion.

How to move Hermes to a Linux server or VPS

Start by in­stalling 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 setup
bash

You can reuse the same Telegram bot token and au­tho­rized user ID. Before starting the bot on the server, however, stop the gateway on your local computer. This prevents both Hermes in­stal­la­tions 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 au­to­mat­i­cal­ly when the server boots:

sudo hermes gateway install --system
sudo hermes gateway start --system
bash

You can check the service status with:

sudo hermes gateway status --system
bash

To view the latest log messages, run:

journalctl -u hermes-gateway -f
bash

With systemd, the gateway runs in the back­ground and can start again after the server reboots. Hermes uses a user-level service for work­sta­tions and a system-wide service for always-on, headless servers. On a VPS, avoid running Hermes with ad­min­is­tra­tor priv­i­leges unless necessary. Where possible, use a dedicated Linux user without un­re­strict­ed root access.

How to run Hermes in Docker

Docker runs ap­pli­ca­tions in isolated con­tain­ers. 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 con­fig­ured, start the official Hermes container in the back­ground as follows:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run
bash

The --restart unless-stopped option restarts the container after a crash or server reboot unless you pre­vi­ous­ly stopped it manually. The mounted ~/.hermes directory stores the con­fig­u­ra­tion, sessions and cre­den­tials outside the temporary container.

Tip

Docker is not required to connect Hermes to Telegram. If you’re new to Hermes, the standard in­stal­la­tion with the systemd service Hermes creates is usually the simpler option.

IONOS CLOUD AI Model Hub
Your gateway to a secure mul­ti­modal AI platform
  • One platform for the most powerful AI models
  • Fair and trans­par­ent token-based pricing
  • No vendor lock-in with open source

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 es­tab­lish­es an outgoing con­nec­tion 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 ad­di­tion­al 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 con­tin­u­ous­ly, check the following:

  • Keep the Telegram bot token in the protected Hermes con­fig­u­ra­tion and nowhere else.
  • Only add the numeric user IDs of people who are ex­plic­it­ly au­tho­rized to TELEGRAM_ALLOWED_USERS.
  • Make sure GATEWAY_ALLOW_ALL_USERS is disabled.
  • Avoid running Hermes with root or ad­min­is­tra­tor priv­i­leges unless necessary.
  • Keep any server and API ports you do not need closed.
  • Do not store cre­den­tials in public Git repos­i­to­ries or publicly ac­ces­si­ble 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 en­vi­ron­ment.

For pro­duc­tion en­vi­ron­ments, 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.

VPS Hosting (Virtual Private Servers)
More scale, same great pricing — with the new VPS+
  • NEW: VM cloning, load balancing, block storage, and more
  • Ideal for agentic AI, LLMs, and au­toma­tion at scale
  • Free 24/7 expert support and 99.99%+ uptime
  • Unlimited traffic and no setup fees

Con­clu­sion

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 con­fig­u­ra­tion and use your user ID to restrict access.

After testing the con­nec­tion, you can install the gateway as a back­ground service and leave it running. If Hermes runs on a Linux server or VPS, this keeps the agent ac­ces­si­ble even when your own computer is switched off. To keep the setup secure, keep the bot token private, allow access only for au­tho­rized user IDs and isolate the agent’s system tools from the host server wherever possible.

Reviewer

Go to Main Menu