Put Hermes in your Telegram

Up until now, Hermes has been stuck in your terminal. This is the step where it escapes. After this walkthrough, you'll be able to message your agent from your phone, from any computer, from wherever you happen to be.

We're doing Telegram because it's the simplest to set up. The same hermes gateway that powers Telegram also runs Discord, Slack, WhatsApp, Signal, and email. Once you've done one, the others follow the same pattern.

What you'll need

A Telegram account on your phone
Hermes installed and working (you should be able to hermes version and hermes doctor without errors)
About fifteen minutes

Step 1: Create a bot with BotFather

Open Telegram and search for @BotFather. It's an official Telegram bot, verified checkmark and all. Start a chat with it.

Send this command:

/newbot

BotFather will ask for:

A display name — what people see in chats. "Hermes" is fine. This can be changed later.
A username — must end in bot. Something like my_hermes_agent_bot. This cannot be changed, and has to be unique across all of Telegram, so you might need a few tries.

Once you pick a valid username, BotFather returns a token that looks like this:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Copy this token and keep it somewhere safe. Anyone with this token can control your bot. Treat it like a password.

Step 2: Find your Telegram user ID

Hermes uses a list of allowed user IDs as a security gate. You want your bot to only talk to you — not every random person who guesses your bot's username.

In Telegram, search for @userinfobot and start a chat. Send it any message (hi works). It replies with your numeric user ID. It looks like a long number — maybe 9 or 10 digits.

Copy that number.

Step 3: Tell Hermes about the bot

Run the gateway setup wizard:

hermes gateway setup

This is an interactive flow. It'll ask which platform you want to set up (pick Telegram), then ask for the bot token you got from BotFather, then ask for the list of allowed user IDs. Paste your user ID when it asks.

If you prefer editing files directly, you can skip the wizard and set the values manually. Open ~/.hermes/.env and add:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=your_telegram_user_id

Replace both values with the actual token and ID. The file is just a simple KEY=value format — one per line, no quotes needed.

Step 4: Start the gateway

hermes gateway

This starts the messaging daemon. Leave the terminal open. You'll see log output as the gateway connects to Telegram and announces itself ready.

If it crashes or complains, check the error message. Most issues at this step are typos in the token or wrong user ID format.

Step 5: Say hi from your phone

Open Telegram, find your bot by its username (the one you picked in Step 1), and send it a message:

hello

Your bot should reply. On the terminal side, you'll see the gateway log the incoming message and Hermes's reply.

Checkpoint — If your bot replies to your message, everything works. You now have a personal AI agent you can message from anywhere in the world.

One brain, many doors

One thing that's easy to miss but important: Hermes doesn't care which platform a message comes from. What you said on Telegram, what you discussed in the terminal CLI, what someone mentioned in Discord — to Hermes it's all the same person talking, and memory is shared.

This means you can assign Hermes a task from your phone during your commute, then sit down at your desk, open the terminal, and say "how's that thing going?" — it knows what you're talking about. No re-explaining context, no copy-pasting. Every platform connects to the same agent instance, the same memory, the same set of Skills.

Things worth trying

Now that it works, here are a few things that make Telegram integration actually useful:

Send a voice note. Record a voice message in Telegram and send it. Hermes will transcribe it and reply in text — or in voice, if you have TTS set up.

Send a screenshot. Drop an image in the chat and ask a question about it. The vision tools take over and Hermes describes or analyzes what it sees.

Ask it to run a shell command on your computer. Remember: the gateway is running on your machine. When you tell it "check if my dev server is running," it actually checks. This is the point where an AI agent on your phone starts feeling like a remote control for your computer.

Running it permanently

Right now the gateway stops when you close your terminal. If you want it to keep running in the background, install it as a service:

hermes gateway install
hermes gateway start

Status check:

hermes gateway status

This sets up a proper background service that survives reboots. You can start, stop, and restart it with the related subcommands.

If something goes wrong

Bot doesn't reply. Check the gateway logs in your terminal — they almost always tell you what's wrong. Most common causes: wrong token, your user ID isn't in TELEGRAM_ALLOWED_USERS, or the gateway process crashed silently. Restart it and watch the output.

"Unauthorized user" message. Your Telegram user ID isn't in the allowed list. Double check the number from @userinfobot and make sure it's in ~/.hermes/.env.

Bot replies but very slowly. First replies are often slow because the model has to warm up. If it stays slow, try switching to a faster model with /model inside a regular terminal chat.

Next up: Stage 4, where Hermes stops being a chatbot and starts being a worker.