hermes-telegram-bot

A Telegram bot powered by Hermes Agent backed by Google Gemini (free tier). Live at @my_hermespro007_bot.

The bot's brain is Hermes Agent's gateway — this repo holds the setup docs, env template, and checklist. You don't write bot code; you configure Hermes and let it run the hermes-telegram toolset (terminal, files, web, memory).

What it does

• Chat with Hermes from Telegram (DMs or groups)
• Hermes can run terminal commands, read/write files, browse the web, use memory
• Runs on a Gemini Flash-Lite model — free, no Cloud billing needed

Prerequisites (one-time)

1. Gemini API key — free at https://aistudio.google.com/apikey (NOT the Gemini Advanced/student web subscription — that has no API quota).
2. Telegram bot token — message @BotFather → /newbot → name + username ending in bot. Copy the 123456:ABC... token.
3. Your numeric Telegram ID — from @userinfobot.

Setup

Copy the env template and fill in your secrets:

cp .env.example .env
# then edit .env with your real values (or let Hermes write it)

Or have Hermes write it directly to Hermes's own .env (C:\Users\<you>\AppData\Local\hermes\.env on Windows):

TELEGRAM_BOT_TOKEN=123456:ABC...
GEMINI_API_KEY=AIza...   # or AQ.Ab...
TELEGRAM_ALLOWED_USERS=<your_numeric_telegram_id>

Set the model (stable, free-tier-friendly Flash-Lite):

hermes config set model.default google/gemini-3.1-flash-lite-preview
hermes config set model.provider gemini

Start the gateway:

hermes gateway run          # foreground
# or persistent on Windows login:
hermes gateway install
hermes gateway status

Then open Telegram → search @my_hermespro007_bot → Start → chat.

Verify it works

# Gemini key valid (200):
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY"

# Telegram token valid ({"ok":true}):
curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe"

# Gateway connected:
grep -iE "telegram connected|Gateway running" ~/.hermes/logs/gateway.log | tail -3

Gotchas (learned the hard way)

1. Gemini API key ≠ Gemini Advanced subscription. Pro models are blocked (limit: 0) without Cloud billing. Use Flash-Lite — it's free.
2. Avoid *-preview Gemini models (e.g. gemini-3-flash-preview) — they return HTTP 503 "high demand" on free keys. Use gemini-3.1-flash-lite-preview.
3. Skip hermes pairing approve — it has a case-sensitivity bug. Use TELEGRAM_ALLOWED_USERS in .env instead.

Checklist

• Gemini API key created (aistudio.google.com/apikey)
• Bot created via @BotFather, token saved
• Numeric Telegram ID from @userinfobot
• .env written with all 3 vars
• Model set to google/gemini-3.1-flash-lite-preview
• hermes gateway run shows "telegram connected"
• Sent a test message in Telegram — bot replied