Muse Bridge

What Muse Bridge does

A client such as 9Router, the Hermes CLI, or a chat bot sends a normal OpenAI chat-completions request to the bridge using the model name muse. The bridge writes the request to a file-based queue and holds the HTTP connection open as a long poll, for up to about four minutes. A separate worker, in the reference setup a scheduled Muse task, polls for pending jobs, picks one up with an atomic lease, composes a reply and posts it back, and the bridge returns that reply to the waiting client as an ordinary OpenAI-style response.

Because the worker pulls jobs outward rather than receiving inbound connections, the setup works behind NAT and over Tailscale or any tunnel. The bridge itself is pure Python standard library with no dependencies to install, and it supports role-based API keys for user and worker traffic, lease expiry, crash recovery and duplicate-answer detection. The README's reference deployment runs 9Router, the bridge, the worker, Hermes and a Telegram bot together on one Linux VPS.

Key features

• OpenAI-compatible /v1/chat/completions and /v1/models endpoints
• File-based job queue with atomic worker leases and crash recovery
• Role-based API keys for user and worker traffic
• Zero external dependencies, pure Python standard library
• Works behind NAT since the worker pulls jobs outward

When to use it

• Connecting a Telegram, Discord or WhatsApp bot to a Hermes agent running inside an isolated Muse VM
• Running 9Router as Hermes Agent's model provider without exposing any inbound port
• Bridging any OpenAI-compatible client to a manually operated reply worker

Who it is for: Developers running Hermes Agent inside a Muse VM who need to reach it from chat bots without inbound network access.

How it fits with Hermes Agent

Built specifically to run 9Router and Hermes Agent together inside the Muse VM, with Hermes configured as a custom OpenAI-compatible provider pointed at 9Router.

How to install Muse Bridge

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

npm install -g 9router
cp bridge.py ~/muse-bridge/
python3 ~/muse-bridge/bridge.py serve

Requirements: Python 3.8+ (standard library only) for the bridge; Node.js and npm for 9Router; the Hermes Agent CLI; a bot token for the Hermes gateway

Note: The worker that actually answers as Muse is not included; the README's reference setup relies on a scheduled Muse task you provide yourself, and the repository has no license file.

FAQ