Wire the Telegram bot
Article 2 locked the box down. Tailscale on, sshd bound to the tailnet interface, ufw deny-by-default. The door is closed. The only people with the key are you, over the tailnet. Now you need something on the other end of that door worth talking to.
This article walks through four steps: get a bot from @BotFather, find your numeric Telegram user ID, drop both into the Hermes profile’s .env, and start the gateway so the bot is reachable from your phone.
This article does not install Hermes. It does not design a persona. Those land in article 4. The reason is sequencing. You cannot talk to a bot that does not exist yet, so we set the bot up first. Until article 4 runs, the gateway’s job is to come up, accept the token, hold a long-polling connection to Telegram, and stay quiet. If you send /start from your phone before article 4 is done, you will get a generic reply. The gateway is alive, but it has no agent and no persona yet. That is the right behaviour at this point in the cluster, not a bug.
Verified 2026-07-20 against Telegram’s official bot docs and against the Hermes source at commit 31c08a9.
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:
/newbotBotFather 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_hereThat 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.
/setdescriptionPick 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
@userinfobotfrom your Telegram account. It replies with your numeric ID in seconds. Try this one first. - DM
@get_id_botinstead if@userinfobotis 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
This section is where the original draft got it wrong. 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.
A fresh Hermes install creates a built-in default profile at ~/.hermes/ itself, not under ~/.hermes/profiles/. The default profile’s .env is therefore ~/.hermes/.env. For an isolated personal bot you want a named profile. Create one:
hermes profile create personalThis makes ~/.hermes/profiles/personal/, drops a fresh .env and config.yaml into it, and, unless you pass --no-alias, also installs a per-profile command alias. I use the explicit hermes -p personal form throughout. The profile name stays visible in the command itself.
Open the profile’s .env:
nano ~/.hermes/profiles/personal/.envAdd exactly these two keys:
TELEGRAM_BOT_TOKEN=110201543:AAH_your_token_here
TELEGRAM_ALLOWED_USERS=123456789TELEGRAM_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. Verified against gateway/config.py lines 1698 to 1724 in commit 31c08a9. 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.
Where this leaves you
Bot credentials in the profile’s .env. Named profile created. The gateway will pick up the Telegram token on its next start. That is article 4’s first job. Until then the bot exists and the credentials are in place, but there is nothing running to receive the connection.
Next: Article 4: Installing Hermes, defining a persona, and choosing a model that fits the workload.
More soon — Michael.
Michael Short is the founder of The Agent Files.