Build agent products without handling harness engineering. HarnessRouter is the infrastructure layer that turns existing harnesses like Codex and Claude Code into plug-and-play agent backends, letting your product run tasks, retrieve results, and switch harnesses through one API.
HarnessRouter implements the Unified Harness Protocol (UHP) and provides an OpenAI Responses-compatible API, handling persistent sessions, streaming progress, files, artifacts, cancellation, and structured failures.
Switch harnesses. Optimize cost and latency.
Eight harness × model configurations on the same task. Each metric compares its best and worst results. The lowest-cost and fastest configurations vary by task. Methodology
31 harness bases today: Codex, Claude Code, Hermes, Pi, DeepSeek Harness, OpenCode, Kilo Code, Qwen Code, Gemini CLI, Cline, Oh My Pi, goose, Kimi Code CLI, MiniMax Code, Aider, OpenHands, CheetahClaws, Grok Build, Agent Zero, System One, Qoder Cloud Agent, MiMo Code, jcode, OpenSquilla, nanobot, ZeroClaw, Mistral Vibe, Docker Agent, fast-agent, Deep Agents Code and Roder. The support matrix shows which run on which provider.
[!TIP]
Get started: Run locally · Integrate into your product · Starter kits · Use managed Cloud
Quickstart
Self-host Community Edition with your own provider keys, on infrastructure you control.
Start with one Docker command, wait for the first launch, then connect a model provider and run your first task.
You need: Docker · About 4 GB of disk · A provider API key
No HarnessRouter account required. No bundled model or trial key.
1. Start HarnessRouter
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
Docker pulls the image if needed. The named volume preserves your database, files, installed harness CLIs, and workspaces between restarts.
Already installed? docker pull harnessrouter/harnessrouter downloads the latest image but does not upgrade a running container. Follow the upgrade and backup guide.
Port 3000 busy? Use -p 127.0.0.1:3100:3000 and open port 3100 instead. Keep the loopback binding while using the initial credentials.
Do not add --user. The entrypoint and Runner need root to manage per-session users. The Console and Gateway run unprivileged; agent processes run as their session’s user.
For version pinning, Compose, and scripted setup, see the setup guide.
2. Wait for the first launch
docker logs -f harnessrouter
The first launch installs the enabled harness CLIs. Continue when the logs show:
[harnessrouter] ready on :3000
Press Ctrl+C to stop following logs. The container keeps running.
If the browser refuses the connection, retry after a few seconds while the Console finishes starting. For a missing harness, check backends available: and any requested but not installed warning in the logs.
3. Open the console
Open http://localhost:3000, or your chosen host port, and sign in as harnessrouter. Your instance made its own password at first start; read it with:
docker exec harnessrouter cat /data/selfhost-initial-password
If you set HR_AUTH_PASSWORD when you started the container, sign in with that instead.
[!WARNING]
Set your own password in Profile. Keep the instance local until you do. Saving briefly restarts the Console and signs out other browsers.
Using an existing volume or custom credentials? Check credential precedence and setup.
These credentials sign you into the Console. You do not need a HarnessRouter API key to run tasks here.
4. Connect a model provider
Open the account menu at the bottom of the rail and choose Bring your own key. Find your provider, press Add key, and paste its API key. Its supported models become available in the Console.
This provider key authorizes model requests. It is separate from the HarnessRouter API key used for product integration below.
5. Set up your first agent
Open Start, say what your agent should do for your users, and press Continue. In Set up an agent harness, leave the agent harness and model on Auto or choose them, then save. HarnessRouter builds the setup on one of your own models: it writes the agent's instructions, picks the harness, model, skills, plugins and tools the job needs, and leaves an example request in the box. Send it to run the first task.
Try an example first. Under Start in HarnessRouter, pick one of the three example jobs. Its request plays back a recorded run, so you see a finished task without spending tokens. Write under it to carry on with your own model.
Change a setup (optional)
Open the setup in Studio and choose Settings to change its model, instructions, skills, plugins, tools, environment and limits. Add plugins, skills, MCP servers and environments for the whole workspace under Add-ons. The agent harness is fixed once a setup is saved: make a new setup to use another.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
