hermes-agent-bridge

Streamable HTTP MCP so a remote MCP client can call a self-hosted Hermes as itself, over tools, not as a chat bot.

Hermes stays on the private network. This bridge runs beside Hermes, talks to its dashboard internally, and is reached from the internet only through an existing Cloudflare Tunnel and Access application. It does not publish the Hermes API.

Install

Choose one of the three paths below. Do not run all three.

• Choose Docker when Hermes and cloudflared already run on the same Docker network.

• Choose Native Linux when the bridge should run directly on a Debian or Ubuntu machine or VM.

• Choose Proxmox when the installer should create and manage a dedicated Debian LXC for the bridge.

Proxmox eventually uses the native service inside its LXC, but you only run the Proxmox command. You do not run the native command yourself afterward.

Before you start

Have these values ready:

• The public MCP hostname, such as mcp.example.com

• The private Hermes dashboard URL reachable from the installation target

• The Hermes kanban board slugs this bridge may access

• The Cloudflare Access team domain and application AUD

• Optional dashboard and Ask-gateway credentials

Cloudflare Tunnel and Access must already exist. The installer does not create or change them, your firewall, or router/NAT rules.

Option A: Docker

Use this when Hermes and cloudflared already share a Docker network. The network must exist before installation. Its name is often hermes.

Run on the Docker host:

curl -fsSL \
  https://raw.githubusercontent.com/nberardi/hermes-agent-bridge/refs/heads/main/install.sh \
  | sudo bash -s -- docker

The installer:

1. Prompts for the bridge configuration and existing Hermes Docker network.

2. Offers to install Docker Engine and Compose from Docker's official apt repository when they are missing on Debian or Ubuntu.

3. Pulls the pinned, non-root GHCR image for the selected version.

4. Starts it on the external Hermes network without publishing a host port.

5. Runs the shared preflight and waits for the container health check.

On success, use the origin printed by the installer for the Cloudflare Tunnel. It will look like:

http://hermes-agent-bridge:8080

This origin works only when cloudflared is attached to the same Docker network.

Option B: Native Linux

Use this for a systemd-based Debian or Ubuntu host or VM on amd64 or arm64. The host must be able to reach Hermes on the private network.

Run on that Linux host:

curl -fsSL \
  https://raw.githubusercontent.com/nberardi/hermes-agent-bridge/refs/heads/main/install.sh \
  | sudo bash -s -- native

The installer:

1. Prompts for the bridge configuration.

2. Installs a private pinned Python 3.12 runtime and hash-locked dependencies under /opt/hermes-agent-bridge without modifying system Python.

3. Creates the non-login hermes-agent-bridge service user.

4. Installs and starts a hardened systemd service.

5. Runs the shared preflight and verifies the loopback health endpoint.

On success, the installer prints the local or LAN origin for the Cloudflare Tunnel, for example:

http://192.0.2.20:8080

The service still runs with python3 -m hermes_agent_bridge, using the private Python installed for that release.

Option C: Proxmox

Use this on a Proxmox VE 8 or 9 host when you want a dedicated LXC. The installer creates the LXC and installs the bridge for you.

Run this directly on the Proxmox VE host:

curl -fsSL \
  https://raw.githubusercontent.com/nberardi/hermes-agent-bridge/refs/heads/main/install.sh \
  | sudo bash -s -- proxmox

The installer:

1. Suggests the next free CT ID. Press Enter to accept it or enter another unused ID.

2. Uses DHCP by default. If you choose static networking, it asks for the LXC IP/CIDR and gateway.

3. Downloads the Proxmox Community Scripts Debian installer and passes it the selected CT ID and network settings in generated mode.

4. Transfers configuration through a protected temporary file.

5. Runs the native installer inside the LXC with pct exec and then removes host-side temporary secrets.

The LXC does not install Docker. On success, the installer prints the CT ID, LXC address, and Tunnel origin, for example:

LXC address: 192.0.2.30
Cloudflare Tunnel origin: http://192.0.2.30:8080

Rerunning the Proxmox command upgrades the recorded LXC. It does not create a new one.

Related MCP server: toolhive-mcp

Finish the Cloudflare setup

After any one installation path succeeds:

1. Route the public hostname on the existing tunnel to the exact origin printed by the installer.

2. Create or select the Cloudflare Access application for that hostname. Its AUD must match CF_ACCESS_AUD in the bridge configuration.

3. Use two separate Access policies:

   • Service Auth for the MCP client's service token

   • Allow for operator login

4. Do not mix Service Auth and Allow in one policy.

The bridge validates Cf-Access-Jwt-Assertion at the origin against the team JWKS and this application's AUD. A Docker or LAN neighbor without a valid JWT still receives 401.

Add the remote MCP connector using:

• URL: https://mcp.example.com/mcp

• Header: CF-Access-Client-Id

• Header: CF-Access-Client-Secret

Replace the example hostname with your Access hostname. The client must not use localhost, RFC1918, or stdio to reach Hermes.

Configuration and upgrades

Every method uses the same guided wizard. Secret prompts are hidden. The final configuration lives at /etc/hermes-agent-bridge.env, owned by root with mode 0600.

Required settings:

• SITE

• PUBLIC_HOSTNAMES

• HERMES_KANBAN_BOARDS

• CF_ACCESS_TEAM_DOMAIN

• CF_ACCESS_AUD

• HERMES_DASHBOARD_URL

Optional settings:

• ALLOWED_ORIGINS

• HERMES_DASHBOARD_TOKEN

• HERMES_API_URL and HERMES_API_KEY for Ask

• BIND_HOST and BIND_PORT

PUBLIC_HOSTNAMES contains DNS hostnames without schemes or paths. ALLOWED_ORIGINS defaults to the HTTPS origin of each public hostname. Board slugs contain lowercase letters, digits, hyphens, or underscores, begin with a letter or digit, and are at most 64 characters.

Use another absolute configuration path with --env-file PATH. For automation, provide a complete env file and add --non-interactive.

To upgrade, rerun the same installation command. The installer uses its current release by default:

curl -fsSL \
  https://raw.githubusercontent.com/nberardi/hermes-agent-bridge/refs/heads/main/install.sh \
  | sudo bash -s -- docker
# Or rerun the native or Proxmox command originally chosen.

Existing settings become the wizard defaults. Releases are installed under /opt/hermes-agent-bridge, and a failed health verification rolls the service and configuration back. There is no automatic update timer.

Check an installation

The shared preflight validates configuration, fetches the Cloudflare Access JWKS, and checks the Hermes dashboard. A dashboard failure is fatal. An unavailable optional Ask gateway is a warning and does not disable the kanban tools.

Native Linux:

/opt/hermes-agent-bridge/current/venv/bin/python \
  -m hermes_agent_bridge check --env-file /etc/hermes-agent-bridge.env

Docker:

docker exec hermes-agent-bridge python -m hermes_agent_bridge check

Proxmox:

pct exec <CTID> -- /opt/hermes-agent-bridge/current/venv/bin/python \
  -m hermes_agent_bridge check --env-file /etc/hermes-agent-bridge.env

Exit codes are 0 for success, including an Ask warning; 2 for configuration; 3 for JWKS; and 4 for a dashboard failure.

Use the bridge

After adding the MCP URL and Cloudflare Access headers to your MCP client, the client can call these tools:

The bridge deliberately cannot approve, assign, start, plan, decompose, or dispatch work. It does not expose the Hermes vault. Its only write operation is creating an unassigned kanban card. The ask tool reports that it is disabled when HERMES_API_URL is not configured or its gateway is down.

Security boundaries

These rules describe what the installation protects:

• /mcp requires a valid Cloudflare Access JWT for the configured team and application AUD. Missing tokens and tokens for another application receive 401.

• Docker does not publish a host port. Cloudflare reaches the bridge through the private Docker network.

• Docker and the installer call GET /healthz locally to confirm that the bridge process started and is listening after a deployment or restart. It does not call Hermes; use the MCP health tool for that. Only a direct loopback request can call /healthz without a JWT.

• The supported MCP endpoint is the Access-protected HTTPS hostname, not a localhost, private-address, or stdio shortcut.

• A failure of the optional Ask gateway does not disable dashboard or kanban tools.

Development

This section is only for contributors changing the bridge itself. It is not part of installation.

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -r requirements-dev.txt
python3 -m pip install -e .
make ci

Python 3.12 or newer is required. uv.lock is the dependency source of truth; requirements-dev.txt is the pinned, hashed development export.