How to Run Hermes Agent on Telegram: Full Setup Guide

Telegram is the natural home for a personal AI agent, and Hermes Agent ships first-class support for it: a polling gateway, DM pairing for security, and voice message handling out of the box. Hermes supports 20+ messaging platforms, but Telegram remains the fastest to set up because a bot identity takes 30 seconds to create (official docs, 2026).

This guide walks through the whole thing: creating the bot, installing the runtime, wiring the gateway, locking it down, and keeping it alive 24/7. At the end, the shortcut for people who'd rather skip the terminal entirely.

---

What You Need Before Starting

Four things, and only one of them costs money:

• A Telegram bot token from BotFather (free, 30 seconds)
• A Linux server if you want 24/7 uptime: 2 vCPU / 4 GB RAM is plenty (from $5/month), or your own machine for testing
• Python 3.11+ and uv: the installer handles both on a fresh box
• An AI provider: an API key (OpenAI, Anthropic, Google, OpenRouter) or, cheaper, your existing ChatGPT Plus subscription through Hermes Agent's native Codex OAuth

If the server part already sounds like a chore, our Hermes Agent hosting guide compares every way to run it, from DIY VPS to managed.

---

Step 1: Create Your Bot With BotFather

Open Telegram, search for @BotFather (the verified one), and send /newbot. Pick a display name, then a username ending in bot. BotFather replies with a token that looks like 1234567890:ABCdef....

That token is a credential, not a detail. Anyone who has it controls your bot. Store it like a password, and if it ever leaks, /revoke in BotFather rotates it instantly.

---

Step 2: Install Hermes Agent

On your server, one line does the heavy lifting:

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

The installer checks Python, installs uv if missing, and sets up the runtime. It has been this smooth since early releases, which partly explains the adoption curve: 100,000+ GitHub stars within seven weeks of the February 2026 launch (Krzysztof Słomka, 2026).

Then pick your model provider with the interactive wizard:

hermes model

Choose an API-key provider, or select OpenAI Codex to authenticate with your ChatGPT Plus subscription via device code. The second option means zero marginal AI cost, which changes the economics of running an agent all day.

---

Step 3: Configure the Telegram Gateway

Give Hermes your bot token in ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=1234567890:ABCdef...

Then start the gateway:

hermes gateway run

Send your bot a message on Telegram. If everything is wired, you'll get an answer, and something important will happen first: a security checkpoint.

---

Step 4: Understand DM Pairing (Do Not Skip This)

By default, when no allowlist is configured, Hermes Agent doesn't answer strangers. An unknown user gets a single-use pairing code instead, and the bot owner approves it from the server:

hermes pairing approve telegram <CODE>

Codes expire after an hour, and repeated failures trigger a lockout. This is the right default for an agent that may hold your calendar, files, and API keys. Resist the temptation of TELEGRAM_ALLOW_ALL_USERS=true unless you're deliberately building a public bot.

---

Step 5: Keep It Alive 24/7

A gateway in a terminal dies with your SSH session. On a server, wrap it in systemd:

[Unit]
Description=Hermes Agent Gateway
After=network-online.target

[Service]
Environment=HERMES_HOME=/root/.hermes
ExecStart=hermes gateway run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable it, and the agent survives reboots and crashes. From there, the operational work begins: Hermes ships fast (version 0.15 alone carried 1,302 commits and 747 merged PRs, per Anthony Maio, 2026), so updates, security patches, and monitoring become a weekly routine.

Common issues worth knowing

• "Conflict: terminated by other getUpdates request": two gateway instances are polling with the same token. Kill the old one; Telegram allows only one poller per bot.
• Bot connects but never answers: check the pairing flow first. An unapproved user is silently ignored by design.
• Auth errors after weeks of uptime: OAuth refresh tokens rotate. Re-run hermes model to re-authenticate.

---

The Shortcut: Managed Hermes Agent on Telegram

Everything above takes a developer 30 to 60 minutes on a good day, plus the ongoing maintenance. The managed alternative compresses it to two inputs: on ClawRapid, you pick a model, paste your BotFather token, and the platform provisions a dedicated hardened VPS, configures the gateway and pairing, and monitors the whole thing. Live in about 2 minutes, 45 EUR/month all included, with $15 of AI credits and ChatGPT Plus support built in.

Same runtime, same pairing security, none of the systemd.

---

Frequently Asked Questions

Can Hermes Agent answer in Telegram groups?

Yes. The gateway handles group chats, with chat-scoped allowlists (TELEGRAM_GROUP_ALLOWED_CHATS) so you authorize an entire group without approving each member. DM pairing still governs private conversations, which keeps the security model coherent.

Does the bot need my Telegram account credentials?

No. It runs entirely on the BotFather token, which is scoped to the bot identity. Your personal account stays untouched, and revoking the token in BotFather instantly cuts access.

How much does a Hermes Telegram bot cost to run?

The software is free (MIT). Self-hosted: $5 to $10/month for the server plus AI usage, which drops to zero marginal cost with ChatGPT Plus auth. Managed on ClawRapid: 45 EUR/month all included. Full breakdown in our Hermes Agent hosting guide.

Can I switch the bot to Discord or Slack later?

Yes. The same Hermes gateway serves 20+ platforms, and on managed hosting the channel is a configuration choice. Discord uses the same pairing model as Telegram; Slack scopes access to your workspace members.

---

Wrap-Up

A Telegram bot is the shortest path to living with an AI agent daily, and Hermes Agent's pairing model makes it safe by default. Build it yourself with the five steps above, or deploy it in 2 minutes on ClawRapid and start the conversation now. Either way, the agent gets more useful every week it stays alive: that's the whole point of the runtime.