fleet-bridge
fleet-bridge is a stdio MCP server (TypeScript, Node >= 18, version 0.1.1) that exposes a single tool surface across two agent runtimes:
- OpenClaw gateway agents, reached over HTTP at
http://{host}:{port}/v1/chat/completionswith Bearer-token auth, plusGET /healthfor health checks. - Hermes agents, reached over SSH by running the
hermesCLI remotely in one-shot mode (hermes -z '<prompt>').
Any MCP client — Claude Code, Zed, or anything else that speaks MCP over
stdio — sees one list of six tools and invokes any agent by name. The bridge
itself is stateless: conversation state for multi-turn sessions is persisted
server-side by the OpenClaw gateway, keyed by a session_key the bridge
generates. Rosters are read once at startup.
fleet-bridge is MIT licensed.
How it works
flowchart LR
subgraph openclaw["OpenClaw gateway agents"]
OA["/v1/chat/completions + /health"]
end
subgraph hermes["Hermes agents"]
HA["ssh user@host binary -z 'prompt'"]
end
BRIDGE["fleet-bridge\nstdio MCP server\nreads rosters at startup\ntokens never leave the box"]
subgraph clients["MCP clients"]
Z["Zed"]
C["Claude Code"]
X["any MCP client"]
end
OA -- "http port/v1/chat/completions (Bearer token)" --> BRIDGE
HA -- "SSH (key auth, BatchMode)" --> BRIDGE
BRIDGE -- "stdio JSON-RPC (MCP)" --> clients
- At startup the bridge reads two roster files:
agents.json(OpenClaw agents) andhermes-agents.json(Hermes agents). Paths are set by theFLEET_BRIDGE_AGENTSandFLEET_BRIDGE_HERMESenvironment variables. - OpenClaw invokes stream SSE-style
data:lines from/v1/chat/completionsand accumulate delta text into a single reply. - Hermes invokes spawn
ssh {ssh_user}@{host} {binary} -z '<prompt>'and return the process stdout. - Every tool returns its result as a text content block. Errors return
isError: truewith afleet-bridge error: ...message.
Security model: agent tokens and Hermes SSH details live only in the roster
files on the box running the bridge and are stripped from every tool output.
Agent traffic is plain http:// by design — run the bridge on a network you
trust (loopback, LAN, or a private overlay). No TLS option in v0.1.
Who it is for
Operators running a fleet of OpenClaw gateway agents and/or Hermes agents who want to drive them from any MCP client without building per-runtime integrations. One bridge instance covers the whole roster; adding an agent is one JSON entry plus a restart.
In this section
- Getting started — install, build, first run
- Configuration — roster schemas and environment variables
- Tools — the six tools, per-tool reference
- MCP clients — wiring into Claude Code, Zed, or any client
- Troubleshooting — timeouts, roster failures, token stripping