Getting started/Install & connect

Install & connect

Install the bridge on a controlled host, configure clients with bearer auth, and smoke-test authorization from another private-network node.

Get the source

Current self-hosted installation requires a local clone because the bridge runs from this repository. A clone-free installer and the managed service are planned, not available today.

bash

git clone https://github.com/AojdevStudio/hermes-satellite.git
cd hermes-satellite

On the Hermes host

Bind only to localhost, VPN, tailnet, or controlled LAN. Public examples use placeholders only.

bash

# choose a private bind address for your environment
export HERMES_ASYNC_BRIDGE_HOST="100.x.x.x"
export HERMES_ASYNC_BRIDGE_PORT="8081"
export HERMES_ASYNC_BRIDGE_TOKEN="$(openssl rand -hex 32)"
python3 apps/hermes-async-bridge/hermes_async_bridge.py

On an MCP client

bash

export HERMES_MCP_TOKEN="<bridge-bearer-token>"
claude mcp add --transport http hermes-async http://<bridge-host>:8081/mcp --header "Authorization: Bearer ${HERMES_MCP_TOKEN}"
codex mcp add hermes-async --url http://<bridge-host>:8081/mcp --bearer-token-env-var HERMES_MCP_TOKEN

yaml

mcp_servers:
  hermes_async:
    url: "http://<bridge-host>:8081/mcp"
    headers:
      Authorization: "Bearer ${HERMES_MCP_TOKEN}"
    timeout: 600
    connect_timeout: 30

Two-way authorization smoke test

The health endpoint is liveness only; it is not authorization proof. Test from a separate private-network client.

satellite runbook

health endpoint -> HTTP 200 liveness only
unauthenticated MCP initialize must fail -> HTTP 401
authenticated MCP initialize must succeed -> HTTP 200 and hermes_* tools discovered