HarnessRouter

Overview

HarnessRouter is the execution and runtime layer between a product and supported agent harnesses. An LLM returns tokens, while a harness gives it a sandbox, tools, and a loop so it returns actual work; HarnessRouter turns existing harnesses such as Codex and Claude Code into plug-and-play agent backends. Applications send a task and receive progress, files, artifacts, final state, and trace through one interface, implemented as the Unified Harness Protocol (UHP) with an OpenAI Responses-compatible API. It is available as a self-hosted Apache 2.0 Community Edition and as managed HarnessRouter Cloud.

Key Features

• One API contract across every supported agent harness, so a product keeps a single integration as harnesses are added
• Implements the Unified Harness Protocol (UHP), an open standard, and exposes an OpenAI Responses-compatible API
• Handles the agent execution lifecycle: sessions, tools, files, artifacts, streaming progress, cancellation, errors, resume, and traces
• Community Edition is Apache 2.0 and runs on infrastructure you control with your own keys, state, and files
• Cloud provisions and operates one isolated sandbox per task, scaling workloads without infrastructure work
• Harness × model routing lets teams benchmark combinations by quality, latency, and cost before changing production traffic

Use Cases

• Build a new agent product on top of Codex, Claude Code, Hermes, or another supported harness
• Migrate an existing managed agent backend to HarnessRouter
• Run a task across harnesses and compare time, cost, and accuracy in the Harness Arena
• Start from open-source starter kits such as Slides, Sheets, Dashboards, and Videos

Getting Started

• Run the container: docker run -d --name harnessrouter -p 127.0.0.1:3000:3000 -v harnessrouter:/data harnessrouter/harnessrouter
• Wait for the first launch by following docker logs until the logs show "[harnessrouter] ready on :3000"
• Open http://localhost:3000 and sign in with username harnessrouter and password harnessrouter
• Connect a model provider under Bring Your Own Key and add its API key so its supported models become available
• Open Agent harnesses, choose a harness, select New task, pick a model, and follow live progress and produced files

Deployment & Requirements

• Docker with about 4 GB of disk and a provider API key; no HarnessRouter account or bundled trial key is required for Community Edition
• Do not add --user: the entrypoint and Runner need root to manage per-session users, while the Console and Gateway run unprivileged and agent processes run as their session's user
• Keep the loopback binding while using the initial credentials
• Use a named volume such as harnessrouter:/data to preserve the database, files, installed harness CLIs, and workspaces between restarts

Before You Adopt

• License: Apache-2.0. Review its terms before using, modifying, or distributing the project.
• Migrating an existing agent workflow requires adopting the API or UHP contract, mapping existing behavior to it, and verifying product-specific behavior on your side.
• Harness capabilities differ, so combinations should be benchmarked before production traffic is switched.
• Model access depends on the third-party provider and the credentials you choose to supply.
• Long exact values such as tokens should be attached as files or passed through the harness environment rather than written into the prompt.