Repolode
Submit
imkofty

imkofty/Hermuse

Scripts and guides to run Hermes Agent, the 9Router model proxy and a Telegram bot gateway on your own Linux server or VM.

View on GitHub
Stars
157
Forks
39
Open issues
0
Last commit
16 days ago

What is it?

Hermuse is a set of shell scripts and documentation for running a personal AI agent stack on your own machine or a VPS. It combines the Hermes Agent CLI, the 9Router OpenAI-compatible model proxy, and a Telegram gateway, so you can chat with your own AI bot around the clock and open a model dashboard from any browser.

The repository covers installation on Ubuntu, a Cloudflare tunnel that exposes the local dashboard through Cloudflare Pages and D1 using a polling client, and supervisors that restart 9Router, the tunnel client and the gateway when they fail. A watchdog script runs from cron, and a separate gateway watchdog detects stalled Telegram polling rather than only checking that the process exists.

The project is aimed at Linux VMs and ships a doctor script, an allowlist-based access model for the Telegram bot, and guides for credential rotation and tunnel database migrations.

Key features

  • 01Installs Hermes Agent, 9Router and Node.js on Ubuntu with a single script.
  • 02Connects a Telegram bot to the Hermes gateway with a numeric user ID allowlist.
  • 03Exposes the local 9Router dashboard publicly through a Cloudflare Pages and D1 polling tunnel.
  • 04Auto-restarts 9Router, the tunnel client and the gateway via supervisor scripts and cron watchdogs.
  • 05Detects stalled Telegram polling using an event-loop heartbeat and adapter activity.
  • 06Provides a doctor script and a migration checker for the tunnel database.

Use cases

  • Running a private Telegram AI assistant on a small Linux VPS.
  • Hosting a self-managed model dashboard reachable from a browser without opening inbound ports.
  • Operating an always-on bot that needs automatic recovery after crashes or reboots.

Quick start

  1. 1

    Install everything (dependencies, Hermes, 9Router)

    bash scripts/install.sh
  2. 2

    Log in to the model provider via OAuth

    hermes setup --portal
  3. 3

    Connect your Telegram bot and set the numeric-ID allowlist

    hermes gateway setup
  4. 4

    Install the Cloudflare tunnel (replace the placeholders with your project and D1 names)

    bash scripts/setup-tunnel.sh <pages-project-name> <d1-name>

Things to know

  • Designed for a Linux server or VM; the README gives no macOS or Windows setup.
  • Requires passwordless sudo or root for the install script.
  • Needs a Cloudflare account and a Telegram bot token to use the full stack.

In collections

Open-source AI agent frameworks & appsSelf-hosted appsAI chatbots & chat clientsOpen-source personal AI agents

Topics

#ai-agent#telegram-bot#self-hosted#cloudflare#llm#automation#openai-compatible#chatbot#hermes-agent#personal-assistant

FAQ

What is Hermuse?
Scripts and guides to run Hermes Agent, the 9Router model proxy and a Telegram bot gateway on your own Linux server or VM. Hermuse is a set of shell scripts and documentation for running a personal AI agent stack on your own machine or a VPS. It combines the Hermes Agent CLI, the 9Router OpenAI-compatible model proxy, and a Telegram gateway, so you can chat with your own AI bot around the clock and open a model dashboard from any browser.
Is Hermuse free to use? What license does it have?
Hermuse is open source under the MIT license. Check the license terms before using it in commercial products.
Is Hermuse still maintained?
Actively maintained. The last commit to Hermuse was on Oct 23, 2026.
What can I use Hermuse for?
Running a private Telegram AI assistant on a small Linux VPS. Hosting a self-managed model dashboard reachable from a browser without opening inbound ports. Operating an always-on bot that needs automatic recovery after crashes or reboots.
How do I install Hermuse?
Install everything (dependencies, Hermes, 9Router): bash scripts/install.sh Log in to the model provider via OAuth: hermes setup --portal Connect your Telegram bot and set the numeric-ID allowlist: hermes gateway setup Install the Cloudflare tunnel (replace the placeholders with your project and D1 names): bash scripts/setup-tunnel.sh <pages-project-name> <d1-name>
Where can I get Hermuse?
The source code and installation instructions are on GitHub: https://github.com/imkofty/Hermuse

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects