imkofty / Hermuse

# Hermuse — self-hosted AI agent stack (Hermes + 9Router + Telegram)
🇬🇧 **English** · 🇮🇩 Indonesia · 🇲🇾 Malaysia
**Hermuse = Hermes + Muse.** Scripts and guides to run Hermes Agent (the AI
agent from Nous Research) + 9Router + a Telegram gateway on your own server —
an exact replica of the stack running on Muse's VM.
**End result:** your personal Telegram AI bot, online 24/7 and ready to chat
anytime, plus a model dashboard you can open from any browser.
## Quick start
What you need:
- A Linux VM like Muse's (Ubuntu 22.04/24.04; 2 vCPU / 4 GB RAM is enough)
- A free Cloudflare account (for the dashboard tunnel)
- A Telegram bot (free via @BotFather)
**New to all of this?** Follow these in order:
1. `bash scripts/install.sh` — installs everything (dependencies, Hermes, 9Router)
Verify: `hermes --version` → prints a version line; `9router --version` → prints a version
2. `hermes setup --portal` — model login; `hermes gateway setup` — connect your Telegram bot
Verify: send `/start` to your bot → it replies (your numeric Telegram ID must be in the gateway allowlist)
3. `bash scripts/setup-tunnel.sh ` — install the Cloudflare tunnel
Verify: `pgrep -f "tunnel-client[.]mjs"` → prints a PID
4. Follow the correct boot order below, then put the watchdog on cron
Verify: `bash scripts/doctor.sh` → summary shows `0 FAIL`
Already comfortable and want the operational scripts directly? See the
file layout table.
## How it works
 [code] 
**Why long-poll?** The `/__tunnel/poll` endpoint holds the connection for
~20 seconds when the queue is empty before responding (or responds immediately
when a request arrives). Without this, polling every 400ms–2.5s would burn
through Cloudflare Workers' **100k requests/day free-tier quota** in hours;
with long-poll, idle usage drops to ~4,300 requests/day. See
`tunnel/pages-tunnel/functions/__tunnel/poll.js` for the implementation.
9Router binds only to `127.0.0.1` (safe, never exposed). The polling tunnel is
used because on the original VM network, WebSocket, QUIC/UDP, and `cloudflared`
connections to the edge all failed — see the
failure archive. On a normal VM/network, plain
`cloudflared` is probably simpler.
## File layout
| File | Role |
|---|---|
| `run-hermes.sh` | Runs the Hermes CLI via a provisioned venv (sets `HERMES_HOME`, minimal `no_proxy`). Adjust `HERMES_VENV` / `HERMES_SRC` at the top of the file. |
| `start-gateway.sh` | Runs the Telegram gateway detached (`setsid`+`nohup`). |
| `start-9router.sh` | 9Router supervisor: binds `127.0.0.1:20128`, auto-restarts on crash. Dashboard password is read from `.dashboard-pw` (600). |
| `start-pages-tunnel.sh` | Tunnel client supervisor (`tunnel-client.mjs`), auto-restart. |
| `restart-9router.sh` | Kills the old 9Router process (safe pattern, anti self-kill) + starts the supervisor detached. |
| `restart-tunnel.sh` | Kills the old tunnel client + starts the supervisor detached. |
| `watchdog.sh` | Checks 9Router, tunnel client, gateway; restarts whatever died. For cron.