Wiring a Telegram bot to your box: BotFather, tokens, and the Hermes .env schema

Create a Telegram bot your Hermes agent can receive messages from and reply to, keeping the box locked while enabling chat from any Telegram client.

Wire the Telegram bot

The cluster is standing. Hetzner box, Tailscale on, sshd bound to the tailnet, ufw deny-by-default. Hermes installed, the personal profile created, a SOUL in place. The agent exists on disk but has no way to receive a message. This article gives it one.

Three steps: get a bot from @BotFather, find your numeric Telegram user ID, drop both into the profile’s .env. Then start the gateway and verify by sending /start from your phone. The gateway is alive, the persona is loaded, and the first reply you get reflects the character you wrote in article 3.

Create the bot in Telegram

Open Telegram and search for @BotFather. The handle has the verified blue tick. If you do not see a tick, it is not the real one. BotFather is the only official way to create a Telegram bot. There is no web dashboard equivalent. Any third-party site that asks you to log into Telegram to create a bot is up to something.

Send:

/newbot

BotFather asks for two things, in order.

A display name. The name that shows in your chat list. Anything human-readable works. I use Hermes Personal.

A unique username. The public handle other people search for. Rules: 5 to 32 characters, case-insensitive, Latin letters, digits, and underscores only, and it must end in bot. Telegram rejects usernames that do not match with a one-line error and lets you try again. Mine is michael_hermes_bot.

After the second answer BotFather replies with a token that looks like:

110201543:AAH_your_token_here

That whole line is the token. Copy it verbatim. Single line, no spaces, no quotes, no wrapping. Anyone who holds that string can read and send messages as your bot, so treat it as a password. Do not paste it into a chat, do not commit it, do not write it into a notes file that syncs somewhere with broad sharing defaults. Keep it in a scratch buffer or a throwaway file you delete after the next section.

Set the bot’s description and bio

Still in the BotFather chat, set a description so anyone who finds the bot by username knows what it is.

/setdescription

Pick your new bot, then send a short description. Telegram caps it at 512 characters. Mine reads:

Personal scheduling and quick-answer assistant for Michael Short. Not for general use.

That last sentence is the load-bearing part. It heads off the inevitable “what is this?” message from anyone who stumbles across the bot.

Optionally set a short bio on the bot’s profile page with /setabouttext. 120 char limit, same flow. Skip /setuserpic and /setcommands for now. Default empty is fine for a single-user personal bot. You can come back and set the command menu later if you change your mind.

Find your numeric Telegram user ID

Hermes recognises allowed users by their numeric Telegram user ID, not by their @username. The reason is durability. Usernames can be changed by the user at any time, and Telegram does not expose username-change history to bots. The numeric ID cannot be reassigned. Same person, same number, forever.

You need that number for TELEGRAM_ALLOWED_USERS. Two ways to get it:

DM @userinfobot from your Telegram account. It replies with your numeric ID in seconds. Try this one first.
DM @get_id_bot instead if @userinfobot is unresponsive. Same purpose, different volunteer-run bot.

The number is a positive integer, usually 9 to 10 digits. Strip everything else. No @, no whitespace. If you allow more than one user later, separate their IDs with commas in the env var.

Wire both into the profile’s `.env`

Telegram credentials do not live in config.yaml. They live in the profile’s .env. The convention is documented at the top of the file itself: Behavioural settings belong in config.yaml, not here. Secrets and credentials in .env, behaviour in config.yaml. Keep the rule.

Open the profile’s .env from article 3:

nano ~/.hermes/profiles/personal/.env

Add exactly these two keys:

TELEGRAM_BOT_TOKEN=110201543:AAH_your_token_here
TELEGRAM_ALLOWED_USERS=123456789

TELEGRAM_BOT_TOKEN is the literal string BotFather gave you, copied verbatim. TELEGRAM_ALLOWED_USERS is your numeric Telegram user ID, no @, no whitespace. Multiple allowed users go in as a comma-separated list: TELEGRAM_ALLOWED_USERS=123456789,987654321. Save the file.

One flag that does not exist. There is no profile-level “enable Telegram” switch in config.yaml. The gateway reads TELEGRAM_BOT_TOKEN from the profile’s .env and auto-enables Telegram when the variable is present. Token in .env and user ID in TELEGRAM_ALLOWED_USERS is the whole security perimeter for a personal bot. Do not go hunting for a flag that is not there.

Start the gateway and verify

Now the agent exists, the SOUL is in place, and the token is in the .env. Time to bring the gateway up.

hermes -p personal gateway install
hermes -p personal gateway start

gateway install sets up the managed service for the personal profile. gateway start launches it as a daemon. Both commands are idempotent. Running them on an already-installed profile is safe.

Verify from your phone. Open Telegram, find the bot by its username, and send /start. A persona-shaped reply is the success signal. If the response is generic, the gateway is alive but the SOUL hasn’t loaded — check the logs and hermes -p personal gateway restart. If it times out with no reply, something failed silently. Check the logs:

hermes -p personal logs -f

The log output shows whether the token was accepted, whether Telegram polling is running, and whether the agent is loading. Most startup issues surface there within the first few lines.

Where this leaves you

Bot credentials in the profile’s .env. Gateway running. The phone, the box, and the agent are now connected. Send it a real question and the reply will reflect the archetype you wrote in article 3. The cluster is complete as a standalone build.

Next: Article 5: Three things I’d do differently if I started this build today.

More soon — Michael.

Michael Short is the founder of The Agent Files.