5-Minute Quickstart

From zero to working Telegram bot.

Prereqs

• A Linux, macOS, or WSL machine (anything with bash)
• A Telegram account
• One provider API key (Anthropic ANTHROPIC_API_KEY or Google GOOGLE_API_KEY / GEMINI_API_KEY — the template defaults to Claude Sonnet with Gemini Flash for the cheap side-tasks; any provider key gets you started)

Step 1 — Install Hermes

curl -sSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes --version          # sanity check

Step 2 — Create your Telegram bot

1. DM @BotFather → /newbot → follow prompts
2. Copy the bot token
3. DM your new bot once (anything) so it can see you
4. Get your Telegram user ID — DM @userinfobot

Step 3 — Drop in a config

# Pull the guide
git clone https://github.com/OnlyTerp/hermes-optimization-guide ~/hermes-guide

# Copy the Telegram-bot template
mkdir -p ~/.hermes
cp ~/hermes-guide/templates/config/telegram-bot.yaml ~/.hermes/config.yaml

Step 4 — Fill in secrets

Create ~/.hermes/.env — lock the permissions down before the keys hit disk:

touch ~/.hermes/.env
chmod 600 ~/.hermes/.env

cat > ~/.hermes/.env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...                 # for the Gemini Flash auxiliary tasks
TELEGRAM_BOT_TOKEN=1234567890:ABC...   # from @BotFather
TELEGRAM_ALLOWED_USERS=1234567         # your numeric ID from @userinfobot
EOF

Step 5 — Start it

hermes gateway

DM your bot. It should reply in seconds. Once it does, Ctrl-C and install it as a service so it survives reboots:

hermes gateway install   # sets up a systemd/launchd service
hermes gateway status    # confirm it's running

Step 6 — Install the skills you'll want

for skill in ~/hermes-guide/skills/*/*/SKILL.md; do
  name=$(basename $(dirname "$skill"))
  ln -sfn "$(dirname "$skill")" "$HOME/.hermes/skills/$name"
done

Then, in a Hermes session (CLI or DM your bot):

hermes skills list         # confirm the symlinked skills are visible (they load at session start)

Now try:

• /audit-mcp — no servers yet, so you'll get "nothing to audit" (expected)
• /cost-report — pulls the built-in cost/usage ledger (hermes insights)
• Ask it anything in freeform — chat just works

Step 7 — Level up

• More platforms: Part 4 (Telegram deep-dive), Part 15 (Teams/LINE/SimpleX/iMessage/WeChat/Android)
• Latest features: Part 22 (Curator, TUI, plugins), Part 23 (Kanban, /goal, Checkpoints v2)
• Desktop app: Part 24 (Hermes Desktop)
• Local inference: Part 25 (NVIDIA local stack)
• Answer quality: Part 26 (Mixture-of-Agents verification)
• Memory that reasons: Part 3 (LightRAG)
• Tools: Part 17 (MCP servers)
• Coding agent driver: Part 18 (Claude Code, Codex, Gemini CLI)
• Production hardening: Part 19 (Security) + Part 20 (Observability)
• One-command VPS install: scripts/vps-bootstrap.sh

Common first-hour issues

Symptom	Fix
Bot doesn't respond	Installed as a service? journalctl --user -u hermes (or hermes gateway status). Running in the foreground? The error is right there in the terminal. 99% of the time it's a missing env var
401 from Anthropic	Check ANTHROPIC_API_KEY has no trailing newline: cat -A ~/.hermes/.env
"skill not found: /cost-report"	Symlinked skills load at the start of a session — start a new session (hermes chat / /new) or restart the gateway, then hermes skills list to confirm
Replies are slow	You're rate-limited on a low Anthropic usage tier. Raise your tier or route to Gemini Flash via the cost-optimized template