Hermuse
Health Pass
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 163 GitHub stars
Code Fail
- process.env — Environment variable access in lib/i18n.mjs
- rm -rf — Recursive force deletion command in scripts/check-i18n.sh
- process.env — Environment variable access in scripts/doctor.sh
- fs module — File system access in scripts/doctor.sh
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Hermuse (Hermes + Muse) — personal AI agent stack built for Muse: Hermes + 9Router + Telegram gateway, automated install, Cloudflare tunnel, watchdog. Runs on a VPS or your own machine; works with other agents & tools too. | Stack agen AI pribadi yang dibangun untuk Muse — jalan di VPS/mesin sendiri, bisa dipakai agen & tool lain juga.
Hermuse — self-hosted AI agent stack (Hermes + 9Router + Telegram)

🇬🇧 English · 🇮🇩 Indonesia · 🇲🇾 Malaysia · 🇻🇳 Việt Nam · 🇮🇳 हिन्दी · 🇯🇵 日本語
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:
bash scripts/install.sh— installs everything (dependencies, Hermes, 9Router)
Verify:hermes --version→ prints a version line;9router --version→ prints a versionhermes setup --portal— model login;hermes gateway setup— connect your Telegram bot
Verify: send/startto your bot → it replies (your numeric Telegram ID must be in the gateway allowlist)bash scripts/setup-tunnel.sh <pages-project-name> <d1-name>— install the Cloudflare tunnel
Verify:pgrep -f "tunnel-client[.]mjs"→ prints a PID- Follow the correct boot order below, then put the watchdog on cron
Verify:bash scripts/doctor.sh→ summary shows0 FAIL
Already comfortable and want the operational scripts directly? See the
file layout table.
How it works
Telegram (you)
│ polling
▼
Hermes gateway ──▶ model:
(run-hermes.sh) ├─▶ Nous (direct, via OAuth / API key)
└─▶ 9Router (127.0.0.1:20128, OpenAI-compatible)
Browser (internet)
│ plain HTTPS
▼
<your-project>.pages.dev (Cloudflare Pages Functions)
│ request/response queue
▼
D1 (tunnel_requests / tunnel_responses tables)
▲ ~20s HTTPS long-poll
│
tunnel-client.mjs (on your VM)
│ forward
▼
9Router at 127.0.0.1:20128
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. Seetunnel/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, plaincloudflared is probably simpler.
File layout
| File | Role |
|---|---|
run-hermes.sh |
Runs the Hermes CLI. Default: forwards to the standard hermes command installed by scripts/install.sh. Optional venv mode: set HERMES_VENV + HERMES_SRC env vars (validated up front; invalid paths fail fast with a clear message). |
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. |
gateway-watch.sh |
Anti-stall watchdog for the Telegram gateway: detects silent stalls via event-loop heartbeat + adapter activity, not just "process alive". For cron (every 5 minutes). |
tunnel-client.mjs |
Polling client: pulls the queue from Pages, forwards to local 9Router, sends responses back. |
tunnel/ |
D1 schema (schema.sql) + Pages Functions + wrangler.toml.example. |
scripts/install.sh |
From-scratch install: dependencies, Node.js LTS, Hermes, 9Router. |
scripts/setup-tunnel.sh |
Tunnel setup: generate key → create D1 → deploy Pages → set secret. |
scripts/setup-tunnel-cloudflared.sh |
Alternative tunnel via cloudflared for normal networks (not the sandbox): install binary, login, create tunnel, route DNS, run instructions. |
docs/arsip-tunnel-gagal.md |
Archive: cloudflared & Tailscale failures on the original VM network (in Indonesian). |
Correct boot order
Run in order (once is enough; supervisors + watchdog handle the rest):
9Router first (detached supervisor, auto-restart):
bash restart-9router.sh
Verify:curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:20128/dashboard→ prints200or307(307 = redirect to login, normal)Tunnel client (needs
TUNNEL_BASE_URLor a.tunnel-urlfile):export TUNNEL_BASE_URL='https://<your-project>.pages.dev'thenbash restart-tunnel.sh
Verify:pgrep -f "tunnel-client[.]mjs"→ prints a PIDTelegram gateway (detached):
bash start-gateway.sh
Verify:pgrep -f "[g]ateway['\", ]+run"→ prints exactly one PID
Then open https://<your-project>.pages.dev in a browser — the 9Router
dashboard should appear. If you get 504 tunnel timeout (client offline?),
the tunnel client isn't running yet.
Watchdog (cron every 5 minutes)
scripts/install.sh installs this automatically (along with the@reboot entry below). The manual step is only needed if you skipped it:
crontab -e
# add this line (adjust the path):
*/5 * * * * /path/to/Hermuse/watchdog.sh
The watchdog checks three things — 9Router (curl to /dashboard), the
tunnel client (pgrep tunnel-client[.]mjs), the Telegram gateway
(gateway.*run) — and restarts whatever died via the restart-* scripts.
It stays silent (writes no log) when everything is healthy; it only logs when
it actually restarts something.
For cron: store the tunnel URL in a
.tunnel-urlfile (chmod 600) in this
folder, since cron doesn't inherit your interactive environment variables:echo -n 'https://<your-project>.pages.dev' > .tunnel-url && chmod 600 .tunnel-url
Anti-stall gateway watchdog (optional but recommended)
The watchdog.sh above only checks "process exists or not". If Telegram
polling stalls while the process is still alive, it slips through.gateway-watch.sh closes that gap with three layers:
- Gateway PID missing → restart immediately.
- Event-loop heartbeat (
$HERMES_HOME/state/gateway.heartbeat, written
automatically by the gateway) stale >120s → restart immediately. - Heartbeat fresh but 0 Telegram adapter activity in
gateway.log
for 15 minutes → mark suspect, restart if confirmed on 2 consecutive runs.
Hard rule: only kill when there is exactly 1 candidate PID (no ambiguity).
Never touches 9Router. Dry-run with no real action:DRY_RUN=1 bash gateway-watch.sh.
crontab -e
# add (can alternate with watchdog.sh):
*/5 * * * * /path/to/Hermuse/gateway-watch.sh
Auto-start after reboot
scripts/install.sh installs this automatically: cron @reboot forstart-all.sh plus the 5-minute watchdog cron (and gateway-watch.sh).
The manual options below are only needed if you skipped that step or
prefer systemd.
scripts/start-all.sh starts any Hermuse component that is down (9Router,
tunnel client, Telegram gateway) — idempotent, running components are untouched:
bash /path/to/Hermuse/scripts/start-all.sh
To run it automatically on every VPS reboot, for a normal Linux VPS:
Option 1 — cron @reboot:
crontab -e
# add:
@reboot sleep 30 && /path/to/Hermuse/scripts/start-all.sh >> /path/to/Hermuse/boot.log 2>&1
Option 2 — systemd user unit (~/.config/systemd/user/hermuse.service):
[Unit]
Description=Hermuse stack (9Router + tunnel + Telegram gateway)
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/path/to/Hermuse/scripts/start-all.sh
RemainAfterExit=yes
[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now hermuse.service
# to run without login: sudo loginctl enable-linger $USER
(Both examples are for a normal VPS/network and haven't been tested on every
distro — adapt to your system. The 5-minute watchdog cron is still recommended
as a safety net.)
Install from scratch
Starting with nothing? Begin here:
bash scripts/install.sh # dependencies + Node.js + Hermes + 9Router + hermes doctor
(needs passwordless sudo, or run as root — the script fails fast otherwise)
Then the model provider & Telegram gateway wizards:
hermes setup --portal # log in to Nous via OAuth (or: hermes model to pick a provider)
hermes gateway setup # enter your Telegram bot token + numeric-ID allowlist
Finally, the Cloudflare tunnel setup:
CLOUDFLARE_API_TOKEN='<token>' bash scripts/setup-tunnel.sh <pages-project-name> <d1-name>
(The Cloudflare token is used transiently — it is not stored in any file.)
Security — don't skip
- Secret files are always
chmod 600and never committed:.env,.tunnel-key,.tunnel-url,.dashboard-pw,wrangler.toml
(all covered by.gitignore). - Telegram gateway: default-deny. Only numeric IDs in
TELEGRAM_ALLOWED_USERScan use the bot (TELEGRAM_BOT_TOKEN+TELEGRAM_ALLOWED_USERSlive in.env). - 9Router dashboard password:
scripts/setup-tunnel.shgenerates.dashboard-pw(600) for you, andstart-9router.shrefuses to boot
while a public tunnel is configured if that file is missing or empty.
Change its contents if you want a password of your own. - Don't expose port 20128 to the internet unprotected; 9Router binds to
127.0.0.1only. - If your Telegram bot token leaks:
/revokein @BotFather, replace it in.env, restart the gateway. - Rotating credentials? Follow the step-by-step credential rotation guide (tunnel key, dashboard password, bot token).
- Tunnel auth fails closed. The Pages functions reject every poll/respond
call unlessTUNNEL_KEYis set as a Pages secret AND matches the client's
key — an unset secret no longer silently means "open tunnel". - Upgrading an existing tunnel database? Run the one-time migrations
in order — old databases need all four, not just the first:wrangler d1 execute <db-name> --remote --file=tunnel/migrations/001-claim-lease.sql
then002-idempotency-ratelimit.sql, then003-response-idempotency.sql,
then004-idempotency-principal.sql
(same command, different--file). Fresh installs don't need them
(schema.sql already includes everything), and re-runningscripts/setup-tunnel.shapplies them for you. Verify afterwards withbash scripts/check-tunnel-schema.sh <db-name>— it prints the exact
fix command for anything still missing. - Payloads are capped at what D1 can store. D1 limits one
string/BLOB/row to 2,000,000 bytes and bodies travel as Base64, so the
tunnel accepts request/response bodies up to 1,350,000 raw bytes
(1,800,000 Base64 chars); larger payloads get a clear 413 instead of a
failed database insert. - Idempotency is bound to the caller. A stored response is replayed
only when the idempotency key, the caller's credential, and the exact
request payload all match. Reusing a key with a different payload gets
a 409 Conflict; another caller's response is never replayed to you. - Watchdog health checks traverse the real tunnel. With a
.health-keyfile (created byscripts/setup-tunnel.sh), the watchdog
and doctor verify the public tunnel end-to-end with an authenticated
nonce probe answered by the local client — an edge 401/403 alone no
longer counts as "healthy". If.tunnel-urlexists but.health-key
is missing or empty, the watchdog logs a hard ERROR and fails the
tunnel check instead of silently skipping the probe.
Notes
What failed on the original network (archive)On the original VM network, two standard approaches failed completely:
- Cloudflare Tunnel (
cloudflared) — QUIC/UDP blocked, TLS to edge IPs
intercepted, proxy refused CONNECT to port 7844. - Tailscale — control plane couldn't get through the network (HTTP 400
from MITM).
Details + sanitized config examples:
docs/arsip-tunnel-gagal.md (in Indonesian).
On a normal VM/network both are probably the easiest route.
License
MIT.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found