lciamp / project-hudson · companion guide

Telegram + Hermes

Sign up for Telegram, create your bot, and wire it to the Hermes gateway on the Mac mini — so the Project Hudson boss agent answers you from your phone.

Before you start

This guide assumes Hermes is already installed on the Mac mini — if it isn't, do step 1 of the install guide first. You'll also need:

  • A phone number that can receive an SMS or a call — Telegram accounts are tied to one.
  • Your phone, for the Telegram app. (Desktop Telegram exists too, but signup happens on the phone.)
  • Terminal access to the Mac mini, to edit ~/.hermes/.env and start the gateway.

Three values connect everything: your bot's token (step 2), your numeric user ID (step 3), and the ~/.hermes/.env file that holds both (step 4).

Sign up for Telegram

  1. Install the app — search "Telegram" in the iOS App Store or Google Play, or grab the desktop apps at telegram.org. Use the phone app for signup.
  2. Register — open the app, enter your phone number, and type in the verification code Telegram sends by SMS (or by call if the SMS doesn't arrive).
  3. Set your name — the display name is all that's required. A public @username is optional; you don't need one for Hermes.
Recommended: two-step verification

In Settings → Privacy and Security → Two-Step Verification, set a password. Your Telegram account will soon be able to drive an agent with shell access on your Mac mini — protect it against SIM-swap takeovers.

Create your bot with @BotFather

Bots are created inside Telegram by talking to @BotFather — Telegram's official bot-management bot. Search for it and check the blue verified badge; imitations exist.

Copy the token — it's the credential Hermes uses to be the bot.

The token is a secret

Anyone holding the token controls your bot. Never commit it to a repo or paste it into chats. If it ever leaks, revoke it immediately in @BotFather with /revoke (or /token to generate a fresh one) and update ~/.hermes/.env.

Get your numeric user ID

Hermes only answers people on its allowlist, and the allowlist uses numeric Telegram IDs — not usernames. Message @userinfobot and it replies with your ID (a number like 123456789). That's the only thing you need from it.

Configure Hermes

On the Mac mini, put both values in Hermes's secrets file:

~/.hermes/.env
TELEGRAM_BOT_TOKEN=<token from BotFather>
TELEGRAM_ALLOWED_USERS=<your numeric user ID>
Never run allow-all

Always set the allowlist. Never enable GATEWAY_ALLOW_ALL_USERS=true — a documented fail-open incident exposed gateways to unauthenticated Telegram DMs, and this bot fronts an agent with shell access.

Start the gateway & test

Terminal
hermes gateway setup     # wizard — picks up the .env values
hermes gateway start
hermes gateway install   # auto-start at login (launchd)
# logs: ~/.hermes/logs/gateway.log

Then, on your phone: search Telegram for your bot's username (@hudson_boss_bot in the example), open the chat, tap Start, and say hello. A reply from Hermes means the whole chain works.

Bind it to Project Hudson

In that first conversation, send the routing instruction so it lands in Hermes's memory:

Send to your bot

For any project-hudson work, use the claude-code skill with workdir /Users/<you>/repos/project-hudson, print mode, and resume sessions rather than starting new ones for follow-ups. Don't answer project-hudson questions from your own tools.

Verify the binding: ask "in the project-hudson repo, list your agents" — expect the 17 specialists. Full detail on this step is in the install guide.

Admitting other people

To let someone else message the bot, use Hermes pairing codes — they expire after an hour, so access is deliberate, one person at a time. Their numeric ID can also be appended to TELEGRAM_ALLOWED_USERS (comma-separated) for permanent access. What you never do is open the gateway to everyone.

Security

  • Keep the token out of git — it lives in ~/.hermes/.env and nowhere else. Revoke via @BotFather the moment you suspect a leak.
  • Don't add the bot to public groups — every message it can read is injection surface for an agent with shell access. Keep it to direct messages.
  • One token, one gateway — two machines running Hermes with the same token will fight over messages. Moving machines? Stop the old gateway first.
  • Ignore third-party "auth bypass" add-ons — they're credential-theft vectors.
  • Reboot test — after hermes gateway install, reboot the mini and confirm the bot still answers before trusting it unattended.

Troubleshooting

SymptomFix
No SMS code at signupWait for the timer, then choose the phone-call option instead.
Bot never repliesGateway isn't running — hermes gateway status on the mini, check ~/.hermes/logs/gateway.log, restart with hermes gateway stop && sleep 5 && hermes gateway start.
"Unauthorized" in the gateway logWrong or revoked token — regenerate with @BotFather's /token and update ~/.hermes/.env.
Replies to you, ignores someone elseThey're not on the allowlist — issue a pairing code or add their numeric ID to TELEGRAM_ALLOWED_USERS.
Answers arrive twice or erraticallyTwo gateways share the token — stop the competing instance.
Silent after rebootlaunchd fell back to a detached process — hermes gateway status, then start it manually.