quickstart.md

5-Minute Quickstart

From zero to working Telegram bot.

Prereqs

• A Linux, macOS, or WSL machine (anything with bash)
• A Telegram account
• An Anthropic API key for the default model
• A Google API key — aistudio.google.com for Gemini Flash classification + LightRAG LLM in the Telegram template
• An OpenAI API key — platform.openai.com/api-keys for LightRAG embeddings in the Telegram template

Step 1 — Install Hermes

curl -sSL https://install.hermes.nous.ai | 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:

cat > ~/.hermes/.env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...                 # required by telegram-bot.yaml for LightRAG embeddings
GOOGLE_API_KEY=AIza...                # required by telegram-bot.yaml for Gemini Flash classification + LightRAG LLM
TELEGRAM_ADMIN_BOT_TOKEN=1234567890:ABC...
TELEGRAM_OWNER_ID=1234567            # your numeric ID from @userinfobot
EOF

chmod 600 ~/.hermes/.env

Step 5 — Start it

hermes run &

DM your bot. It should reply in seconds.

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
hermes /reload

Now try:

• /audit-mcp — no servers yet, so you'll get "nothing to audit" (expected)
• /cost-report — shows this session's token usage
• Ask it anything in freeform — chat just works

Step 7 — Level up

• More platforms: Part 4 (Telegram deep-dive), Part 15 (iMessage/WeChat/Android)
• Latest features: Part 22 (Curator, TUI, plugins), Part 23 (Kanban, /goal, Checkpoints v2)
• 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	journalctl --user -u hermes — 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"	hermes /reload after symlinking skills
Replies are slow	You're on Anthropic free tier — rate-limited. Upgrade or route to Gemini Flash via the cost-optimized template