🤖 Hermes Quickstart

A Telegram AI bot, up and running in 5 minutes on a blank Ubuntu VPS.

With a single command you get:

🤖 A Telegram bot you can chat with
🌐 A web dashboard to monitor and switch AI models
🆓 Free AI models by default (via OpenRouter free tier — no credit card)
⚡ Many more model choices (Claude, GPT, MiMo, Gemini, and more via the dashboard)

📋 What you need

	What	How to get it
🖥️	Ubuntu VPS (22 or 24)	Contabo, Hetzner, DigitalOcean, etc. Minimum 1 GB RAM
🔑	root access to the VPS	Via SSH `ssh root@your-vps-ip`
🤖	Telegram Bot Token	Chat @BotFather → `/newbot` → follow the prompts
🆔	Your Telegram ID	Chat @userinfobot → it returns your numeric ID
🆓	OpenRouter API Key	Sign up at openrouter.ai/keys → key starts with `sk-or-v1-...` (free, no card)

🚀 Install (one command)

Replace xxx with your tokens, then paste into the VPS terminal:

curl -fsSL https://raw.githubusercontent.com/FlipZ3ro/hermes-quickstart/main/install.sh | \
  TELEGRAM_BOT_TOKEN=xxxxxxx \
  TELEGRAM_ALLOWED_USERS=xxxxxxx \
  OPENROUTER_API_KEY=sk-or-v1-xxxxxxx \
  bash

Real example:

curl -fsSL https://raw.githubusercontent.com/FlipZ3ro/hermes-quickstart/main/install.sh | \
  TELEGRAM_BOT_TOKEN=8123456789:AAFabcdefghijklmnop \
  TELEGRAM_ALLOWED_USERS=1402173933 \
  OPENROUTER_API_KEY=sk-or-v1-abcdef0123456789 \
  bash

⏳ Wait 5-8 minutes. When it finishes, a green box appears with the dashboard password + URL.

💡 Want a different free model? Add OPENROUTER_MODEL=x-ai/grok-4-fast:free (or any other free model id). Full list: openrouter.ai/models — any id ending in :free costs zero.

💡 Also want MiMo direct? Pass MIMO_TOKEN=tp-... at install time to enable the hermes-mimo CLI as well.

✅ After install — check the bot

Open Telegram → find your bot (the name you set in @BotFather)
Send /start or just type hello
The bot replies within 2-4 seconds using the free model

If the bot is silent, check the logs:

journalctl -u hermes-gateway -f

🗺️ How it works (full flow)

   [1] Install once                       [2] Add provider manually               [3] Switch model via CLI
   ━━━━━━━━━━━━━━━━━━━━━                ━━━━━━━━━━━━━━━━━━━━━━━━━              ━━━━━━━━━━━━━━━━━━━━━━━━
        ┌────────────┐                    ┌────────────┐                          ┌────────────┐
        │  curl|bash │                    │  Dashboard │  ←─ paste API key ─┐    │   SSH to   │
        │ (5-8 min)  │                    │  9router   │     (Claude / GPT  │    │    VPS     │
        └─────┬──────┘                    └─────┬──────┘      / MiMo / etc) │    └─────┬──────┘
              │                                  │                           │          │
              ▼                                  ▼                           │          ▼
        ┌────────────┐                    ┌────────────┐                     │   ┌────────────┐
        │ Bot, 9R,   │                    │  Provider  │                     │   │ Type e.g.  │
        │ Hermes UP  │                    │ unlocked   │                     │   │ hermes-9r..│
        │ (OR free)  │                    └────────────┘                     │   │  /  -or    │
        └────────────┘                                                        │   └─────┬──────┘
                                                                              │         │
                                                                              │         ▼
                                                                              │   ┌────────────┐
                                                                              │   │ Bot uses   │
                                                                              │   │ the new    │
                                                                              │   │ model      │
                                                                              │   └────────────┘
                                                                              │
                                              Add once, switch anytime ──────┘

Step 1 — Install (once, at the start)

Run the curl one-liner on a blank VPS (see Install above). When done, you have:

A live Telegram bot (defaults to OpenRouter free tier — no charges)
The 9router dashboard at http://VPS-IP/dashboard

Step 2 — Add a provider (optional, in the dashboard)

You already have OpenRouter free running out of the box. Add more providers only when you want more models or higher rate limits. Once per provider — after that the models stay available forever.

Open http://VPS-IP/dashboard → log in with the password (find it with grep INITIAL_PASSWORD /opt/9router/.env)
Sidebar → Providers → + Add
Pick a provider (OpenRouter, Xiaomi MiMo, Claude Code, OpenCode Free, Cerebras, etc.)
Paste the API key / OAuth login
Save → 9router validates automatically

Popular providers:

Provider	How to get it	Notes
OpenRouter	openrouter.ai/keys	Already added by the installer. Free tier has dozens of models with `:free` suffix
Xiaomi MiMo (Token Plan)	mimo.xiaomi.com → Token Plan	Optional. Pass `MIMO_TOKEN=` at install to also enable
OpenCode Free	No signup, add directly	Free Claude Sonnet, rate-limited
Cerebras	cerebras.ai → free key	Free, blazing-fast Llama 70B
Groq	groq.com → API key	Free, high throughput
Google Gemini	aistudio.google.com	Free 60 req/min
Claude Code (OAuth)	Log in with a Claude Pro account	⚠️ Ban risk — use a spare account

Step 3 — Switch model (anytime, via CLI)

💡 Install via npm (on any machine that already has Hermes Agent):
npm install -g hermes-mimo
This gives you three global commands: hermes-openrouter, hermes-mimo, hermes-9router. The CLI auto-detects the hermes binary from PATH (falling back to /root/.local/bin/hermes). Linux/macOS. On a VPS created by install.sh, both commands are already pre-installed with the token embedded — so the npm package is for manual/reference use.

Once a provider is added, its models are usable immediately. Change the bot's default model with these commands:

# Direct OpenRouter (default, free)
hermes-openrouter                                  # default: gpt-oss-20b:free
MODEL=x-ai/grok-4-fast:free hermes-openrouter     # switch model
MODEL=meta-llama/llama-3.3-70b-instruct:free hermes-openrouter

# Via 9router pool (any added provider)
hermes-9router                                    # default: OpenRouter free via pool
MODEL=cc/claude-opus-4-6 hermes-9router           # switch to Claude Opus (via 9router)
MODEL=cc/claude-haiku-4-5-20251001 hermes-9router # switch to Claude Haiku
MODEL=xmtp/mimo-v2.5 hermes-9router               # switch to MiMo

# Direct MiMo (only if MIMO_TOKEN was set at install)
hermes-mimo

The bot picks up the new model automatically — no manual restart needed.

💡 Tip: find the full model ID in the dashboard → Providers → click a provider → Available Models tab. Copy the ID (e.g. openrouter/x-ai/grok-4-fast:free or cc/claude-opus-4-6).

`hermes-openrouter` vs `hermes-mimo` vs `hermes-9router`

	`hermes-openrouter`	`hermes-mimo`	`hermes-9router`
Routing	Bot → OpenRouter direct	Bot → MiMo direct	Bot → 9router → any provider
Cost	🆓 Free tier default	💰 Paid Token Plan	Depends on backend
Speed	⚡ Fast (1 hop)	⚡ Fastest (1 hop)	Slightly slower (+20-50ms)
Multi-provider	❌ OpenRouter only	❌ MiMo only	✅ Every added provider
Auto fallback	❌	❌	✅ Switches when quota runs out
Usage in dashboard	❌ Bypassed	❌ Bypassed	✅ Fully tracked
Available always?	✅ Installed by default	Optional (needs MIMO_TOKEN)	✅ Installed by default

Rule of thumb:

Use hermes-openrouter for free chat that just works
Use hermes-mimo if you have a Token Plan and want lowest latency
Use hermes-9router if you want monitoring + multi-model + automatic fallback (recommended for production)

🌐 Web dashboard

Open in a browser:

http://YOUR-VPS-IP/dashboard

Log in with the password shown at the end of the install (write it down!).

In the dashboard you can:

➕ Add other AI providers (Claude, OpenAI, Gemini, Cerebras, free tiers)
📊 View token usage per provider
🔁 Set up automatic fallback when quota runs out
🔑 Create API keys for other apps

❓ FAQ

Bot replies but it's slow / choppy

Try a faster free model:

MODEL=x-ai/grok-4-fast:free hermes-openrouter
# or if you configured MiMo:
hermes-mimo

OpenRouter rate limit hit

Free models on OpenRouter have per-key limits. Options:

Switch to a different free model: MODEL=meta-llama/llama-3.3-70b-instruct:free hermes-openrouter
Add another provider in the dashboard (Cerebras, Groq, Gemini all have generous free tiers)
Route via 9router so it auto-fails-over: hermes-9router

Bot is totally silent / "something went wrong" error

systemctl restart hermes-gateway
journalctl -u hermes-gateway -n 30

Still broken? Paste the log output to Issues.

Forgot the dashboard password

grep INITIAL_PASSWORD /opt/9router/.env

That's your password.

Let other people chat with the bot

Edit /root/.hermes/.env → add their Telegram IDs separated by commas:

TELEGRAM_ALLOWED_USERS=1402173933,987654321,555000111

Then:

systemctl restart hermes-gateway

Update 9router to the latest version

cd /opt/9router && systemctl stop 9router && \
  git pull && npm install && npm run build && \
  cp -r public .next/standalone/ && \
  cp -r .next/static .next/standalone/.next/ && \
  systemctl start 9router

Update Hermes Agent

pipx upgrade hermes-agent
systemctl restart hermes-gateway

Reinstall from scratch (if badly broken)

# Stop & remove first
systemctl stop 9router hermes-gateway 2>/dev/null
hermes gateway uninstall --system 2>/dev/null
pipx uninstall hermes-agent 2>/dev/null
rm -rf /opt/9router /var/lib/9router /root/.hermes
rm -f /etc/systemd/system/9router.service
rm -f /etc/nginx/sites-enabled/9router /etc/nginx/sites-available/9router
systemctl daemon-reload

# Then run install.sh again
curl -fsSL https://raw.githubusercontent.com/FlipZ3ro/hermes-quickstart/main/install.sh | \
  TELEGRAM_BOT_TOKEN=... TELEGRAM_ALLOWED_USERS=... OPENROUTER_API_KEY=sk-or-v1-... bash

Full env var reference

Required:

Var	Example
`TELEGRAM_BOT_TOKEN`	`8123:AAF...`
`TELEGRAM_ALLOWED_USERS`	`1402173933`
`OPENROUTER_API_KEY`	`sk-or-v1-...`

Optional:

Var	Default	Purpose
`OPENROUTER_MODEL`	`openai/gpt-oss-20b:free`	Any free model id from openrouter.ai
`MIMO_TOKEN`	(unset)	Set to also enable `hermes-mimo` CLI
`MIMO_REGION`	`sgp`	`sgp` / `cn` / `ams` (only relevant if MIMO_TOKEN set)
`NINER_PASSWORD`	random 16 chars	9router dashboard password
`VPS_IP`	auto-detect	Public IP to embed in the dashboard
`SKIP_UFW=1`	(firewall on)	Skip firewall setup

Example with a custom model + MiMo enabled:

curl -fsSL https://raw.githubusercontent.com/FlipZ3ro/hermes-quickstart/main/install.sh | \
  TELEGRAM_BOT_TOKEN=... \
  TELEGRAM_ALLOWED_USERS=... \
  OPENROUTER_API_KEY=sk-or-v1-... \
  OPENROUTER_MODEL=x-ai/grok-4-fast:free \
  MIMO_TOKEN=tp-... \
  NINER_PASSWORD=MyPass123! \
  bash

🔒 Security

✅ Dashboard password is randomly generated by default
✅ The Telegram bot only responds to whitelisted users
✅ All secrets stored in .env files with mode 600 (root-only read)
✅ SSH key required (the script does not set up password SSH)
⚠️ The dashboard is exposed on port 80 without HTTPS. For production, use a domain + Cloudflare / Let's Encrypt.

🧩 What gets installed

	Component	Purpose
🚏	9router	Model-router dashboard, OpenAI-compatible API
🤝	Hermes Agent	AI agent with Telegram, tool use, memory
🌐	nginx	Reverse proxy port 80 → 9router
🟢	Node.js 22	Runtime for 9router
🐍	Python 3.12 + pipx	Runtime for Hermes
🛡️	UFW firewall	Allow ports 22 & 80 only

📂 Important files after install

File	Contents
`/opt/9router/.env`	Dashboard password + secrets
`/root/.hermes/config.yaml`	Hermes model settings
`/root/.hermes/.env`	Telegram token + whitelist
`/usr/local/bin/hermes-openrouter`	CLI: switch to OpenRouter direct (default)
`/usr/local/bin/hermes-mimo`	CLI: switch to MiMo (only if `MIMO_TOKEN` was set)
`/usr/local/bin/hermes-9router`	CLI: switch to 9router pool

🛠️ For developers

Want to contribute or hack on it?

git clone https://github.com/FlipZ3ro/hermes-quickstart.git
cd hermes-quickstart

# Edit install.sh
# Syntax check:
bash -n install.sh

# Test on a dev VPS
scp install.sh root@dev-vps:/tmp/
ssh root@dev-vps "TELEGRAM_BOT_TOKEN=xxx ... bash /tmp/install.sh"

PRs welcome on GitHub.

📜 License

MIT — free to use, modify, and distribute.

🙏 Credits

9router by @decolua
Hermes Agent by Nous Research
OpenRouter for the free-tier model pool
Xiaomi MiMo model family
Bootstrap by @FlipZ3ro

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
bin		bin
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.id.md		README.id.md
README.md		README.md
install.sh		install.sh
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🤖 Hermes Quickstart

📋 What you need

🚀 Install (one command)

✅ After install — check the bot

🗺️ How it works (full flow)

Step 1 — Install (once, at the start)

Step 2 — Add a provider (optional, in the dashboard)

Step 3 — Switch model (anytime, via CLI)

`hermes-openrouter` vs `hermes-mimo` vs `hermes-9router`

🌐 Web dashboard

❓ FAQ

🔒 Security

🧩 What gets installed

📂 Important files after install

🛠️ For developers

📜 License

🙏 Credits

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🤖 Hermes Quickstart

📋 What you need

🚀 Install (one command)

✅ After install — check the bot

🗺️ How it works (full flow)

Step 1 — Install (once, at the start)

Step 2 — Add a provider (optional, in the dashboard)

Step 3 — Switch model (anytime, via CLI)

hermes-openrouter vs hermes-mimo vs hermes-9router

🌐 Web dashboard

❓ FAQ

🔒 Security

🧩 What gets installed

📂 Important files after install

🛠️ For developers

📜 License

🙏 Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`hermes-openrouter` vs `hermes-mimo` vs `hermes-9router`