🤖 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
⚡ Many model choices (MiMo, Claude, GPT, Gemini, and more)

📋 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
🔐	MiMo API Key	Sign up at mimo.xiaomi.com → Token Plan → key starts with `tp-...`

🚀 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 \
  MIMO_TOKEN=tp-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 \
  MIMO_TOKEN=tp-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  bash

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

✅ 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

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..│
        └────────────┘                    └────────────┘                     │   │  /  -mimo  │
                                                                              │   └─────┬──────┘
                                                                              │         │
                                                                              │         ▼
                                                                              │   ┌────────────┐
                                                                              │   │ 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 MiMo)
The 9router dashboard at http://VPS-IP/dashboard

Step 2 — Add a provider (manually in the dashboard, as needed)

Add the AI providers you want to use. 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 (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
Xiaomi MiMo (Token Plan)	mimo.xiaomi.com → Token Plan	Already added automatically by the installer
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 two global commands: 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 two commands:

# Use MiMo directly (fastest, no 9router)
hermes-mimo

# Use the 9router pool (every provider you've added)
hermes-9router                                    # default: MiMo via 9router
MODEL=cc/claude-opus-4-6 hermes-9router           # switch to Claude Opus
MODEL=cc/claude-haiku-4-5-20251001 hermes-9router # switch to Claude Haiku
MODEL=oc/claude-sonnet-4.5 hermes-9router         # via OpenCode Free
MODEL=xmtp/mimo-v2.5-pro hermes-9router           # MiMo Pro

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. cc/claude-opus-4-6).

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

	`hermes-mimo`	`hermes-9router`
Routing	Bot → MiMo direct	Bot → 9router → any provider
Speed	⚡ Fastest (1 hop)	Slightly slower (+20-50ms)
Multi-provider	❌ MiMo only	✅ Every added provider
Auto fallback	❌	✅ Switches when quota runs out
Usage in dashboard	❌ Bypassed	✅ Fully tracked
Model switching	MiMo region only	Any provider, freely

Rule of thumb:

Use hermes-mimo if you only need MiMo and want maximum speed
Use hermes-9router if you want monitoring + multi-model + fallback (recommended)

🌐 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

Switch to a faster model:

hermes-mimo                          # default mimo-v2.5
# or via 9router with Haiku:
MODEL=cc/claude-haiku-4-5-20251001 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=... MIMO_TOKEN=... bash

Full env var reference

Required:

Var	Example
`TELEGRAM_BOT_TOKEN`	`8123:AAF...`
`TELEGRAM_ALLOWED_USERS`	`1402173933`
`MIMO_TOKEN`	`tp-...`

Optional:

Var	Default	Purpose
`NINER_PASSWORD`	random 16 chars	9router dashboard password
`MIMO_REGION`	`sgp`	`sgp` / `cn` / `ams`
`VPS_IP`	auto-detect	Public IP to embed in the dashboard
`SKIP_UFW=1`	(firewall on)	Skip firewall setup

Example with a custom password:

curl -fsSL https://raw.githubusercontent.com/FlipZ3ro/hermes-quickstart/main/install.sh | \
  TELEGRAM_BOT_TOKEN=... \
  TELEGRAM_ALLOWED_USERS=... \
  MIMO_TOKEN=... \
  NINER_PASSWORD=MyPass123! \
  MIMO_REGION=cn \
  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-mimo`	CLI: switch to MiMo
`/usr/local/bin/hermes-9router`	CLI: switch to 9router

🛠️ 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
Xiaomi MiMo model family
Bootstrap by @FlipZ3ro

Name		Name	Last commit message	Last commit date
Latest commit History 5 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 (manually in the dashboard, as needed)

Step 3 — Switch model (anytime, via CLI)

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

🌐 Web dashboard

❓ FAQ

🔒 Security

🧩 What gets installed

📂 Important files after install

🛠️ For developers

📜 License

🙏 Credits

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

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 (manually in the dashboard, as needed)

Step 3 — Switch model (anytime, via CLI)

hermes-mimo vs hermes-9router

🌐 Web dashboard

❓ FAQ

🔒 Security

🧩 What gets installed

📂 Important files after install

🛠️ For developers

📜 License

🙏 Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

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

Packages