# 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 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 background service; `hermes doctor` helps 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](https://www.ionos.ca/digitalguide/websites/web-development/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](https://www.ionos.ca/digitalguide/online-marketing/online-sales/what-is-a-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:

```bash
hermes
```

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 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:

```text
/newbot
```

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](https://www.ionos.ca/digitalguide/websites/web-development/what-is-an-api/) token. This token identifies 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 screenshots, public documents, forum posts, or publicly accessible Git [repositories](https://www.ionos.ca/digitalguide/server/know-how/repository/). 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?

<table>
  <thead>
    <tr>
      <th><strong>Configuration detail</strong></th>
      <th><strong>What it contains</strong></th>
      <th><strong>How to get it</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>TELEGRAM_BOT_TOKEN</td>
      <td>Secret API token for your Telegram bot</td>
      <td>@BotFather sends it after you create the bot with /newbot</td>
    </tr>
    <tr>
      <td>TELEGRAM_ALLOWED_USERS</td>
      <td>Your numeric Telegram user ID</td>
      <td>Send @userinfobot a message to get your user ID</td>
    </tr>
    <tr>
      <td>Bot username</td>
      <td>Publicly visible username of the bot that ends in “bot”</td>
      <td>Choose it when creating the bot with @BotFather</td>
    </tr>
  </tbody>
</table>

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:

```bash
hermes gateway setup
```

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 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 authorized. For a bot used exclusively by you, a fixed allowlist of user IDs is the simplest and most transparent 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 authorized. 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:

```bash
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
```

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 conversations in separate sessions, but the underlying agent capabilities remain available to all authorized 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:

```bash
hermes gateway run
```

The 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:

1. **Check the session status**: Send `/status`. Hermes should show information 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 conversation**: Send `/new` to 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:

```bash
hermes gateway install
```

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

```bash
hermes gateway start
hermes gateway stop
hermes gateway status
```

After making changes to the Telegram configuration, restart the gateway:

```bash
hermes gateway stop
hermes gateway start
```

Alternatively, you can restart it directly with:

```bash
hermes gateway restart
```

hermes 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:

```bash
hermes gateway status
```

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 troubleshooting step, run:

```bash
hermes doctor
```

Hermes 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:

```bash
hermes doctor --fix
```

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 connection?

To see connection errors, stop the background service and run the gateway in the foreground again:

```bash
hermes gateway stop
hermes gateway run
```

Any 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:

```bash
hermes gateway setup
```

You can reuse the same Telegram bot token and authorized 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:

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

You can check the service status with:

```bash
sudo hermes gateway status --system
```

To view the latest log messages, run:

```bash
journalctl -u hermes-gateway -f
```

With 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](https://www.ionos.ca/digitalguide/server/know-how/docker-container/). 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:

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

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

Tip [Docker](https://www.ionos.ca/digitalguide/server/know-how/what-is-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 authorized to `TELEGRAM_ALLOWED_USERS`.
- Make sure `GATEWAY_ALLOW_ALL_USERS` is 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](https://www.ionos.ca/digitalguide/server/know-how/what-is-a-vps-virtual-private-server/), 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 authorized user IDs and isolate the agent’s system tools from the host server wherever possible.


This is a markdown version of: [https://www.ionos.ca/digitalguide/server/configuration/connect-hermes-agent-to-telegram/](https://www.ionos.ca/digitalguide/server/configuration/connect-hermes-agent-to-telegram/) for AI/LLM consumption.