Hermes Agent Telegram Bot Setup: Secure Remote Access (2026)

Before you start

You need a working Hermes installation and a configured model provider. The Telegram gateway is only the transport; it does not supply the model.

Install Hermes from the official installer if needed:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Do not paste real bot tokens into chat, screenshots, or a repository. Hermes stores the Telegram token in its local environment file.

Step 1: Create a bot with BotFather

Open Telegram and message @BotFather. Use /newbot, choose a display name and username, then copy the token BotFather returns.

Anyone holding this token can control the Telegram bot account. If it leaks, rotate it in BotFather and update Hermes immediately.

Step 2: Find your numeric Telegram user ID

Hermes authorizes numeric user IDs, not Telegram usernames. The official guide recommends messaging @userinfobot or @get_id_bot. Save the number it returns.

Group and supergroup chat IDs can be negative. Those IDs belong in the group-chat authorization setting, not the sender user allowlist.

Step 3: Run the gateway wizard

Use the supported setup path:

hermes gateway setup

Select Telegram, then enter the bot token and your allowed numeric user ID. The equivalent manual values in ~/.hermes/.env are:

TELEGRAM_BOT_TOKEN=your-token-from-botfather
TELEGRAM_ALLOWED_USERS=123456789

Start the gateway:

hermes gateway

Send the bot a direct message. DMs respond without an @mention; groups can require a mention depending on your configuration.

Step 4: Keep the gateway closed by default

Do not set TELEGRAM_ALLOW_ALL_USERS=true for a personal agent with terminal, browser, files, or credentials. Use one of these safer paths:

• Put trusted numeric IDs in TELEGRAM_ALLOWED_USERS.
• Let an unknown trusted user request a one-time DM pairing code, then approve it locally:

hermes pairing approve telegram XKGH5N7P
hermes pairing list
hermes pairing revoke telegram 123456789

Pairing codes expire after one hour and are rate-limited. The owner still approves access from the machine running Hermes.

Step 5: Set a home channel

In the Telegram chat that should receive scheduled output, run:

/sethome

Cron jobs and proactive messages use this destination. A successful cron task without a home channel has nowhere to send its result.

Step 6: Choose group behavior deliberately

For a group, a conservative configuration requires explicit mentions and can ignore selected forum topics:

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  ignored_threads:
    - 31
    - 42

Telegram topics can also route different profiles through one bot. Treat each profile as a separate agent with its own memory, credentials, and skills. See Hermes Bot Mode before building a multi-bot room.

Common failures

The bot exists but says nothing

Confirm the gateway process is running, then check whether your numeric ID is allowed. Hermes fails closed: an unlisted and unpaired user is denied rather than silently receiving agent access.

Cron runs but no message arrives

Run /sethome in the intended chat. For forum topics, configure the cron thread ID if results should land in a specific topic.

The bot answers every group message

Turn mention requirements on. In a shared room, free response can trigger the agent on unrelated conversation and create unnecessary model calls.

A teammate lost access

Use hermes pairing list or inspect the configured allowlist. Usernames are not authorization IDs and can change; numeric IDs are the reliable value.

After it works

Start with one low-risk remote task. Do not grant personal email, production cloud, and unrestricted shell access on the first day. Add permissions after the bot proves it can follow the workflow and after you have reviewed its memory and skill-write settings.

Official references

• Hermes Telegram setup
• Hermes messaging gateway
• Hermes security guide

Related guides

• Hermes Discord bot setup
• Hermes Bot Mode
• Hermes Agent mastery tips
• Agent Docker sandbox security