HarnessRouter: Unified Interface for AI Agent Harnesses

Summary

HarnessRouter Community Edition provides a self-hosted, Apache-2.0 licensed unified interface for various AI agent harnesses like Codex, Claude Code, and Hermes. It allows users to run multiple agents through a single API, offering features such as sessions, streaming, file handling, and cancellation. The project implements the open-standard Unified Harness Protocol (UHP), ensuring users maintain control over their keys and infrastructure.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

HarnessRouter Community Edition is an open-source, self-hosted platform that provides a unified interface for various AI agent harnesses. It allows developers to integrate and manage different agent backends, such as Codex, Claude Code, Hermes, and DeepSeek Harness, through a single, consistent API. By implementing the open-standard Unified Harness Protocol (UHP), HarnessRouter simplifies the development of agent products, abstracting away complex harness engineering.

Why Use It and Benefits

HarnessRouter offers significant advantages for building agent-powered applications. It eliminates the need to handle individual harness integrations, allowing products to switch between different agent backends to optimize for cost and latency. Users benefit from full control over their infrastructure, credentials, and state, as provider keys, sessions, files, and workspaces remain self-hosted. The platform provides real workspaces, native filesystem, shell, and Git workflows, ensuring robust and secure agent operations without Console product analytics.

Installation

To get started with HarnessRouter Community Edition, you need Docker and a provider API key.

Start HarnessRouter:
```
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter
```
This command pulls the Docker image and starts the container, preserving your data across restarts with a named volume.
Wait for the first launch:
Monitor the logs until you see [harnessrouter] ready on :3000.
```
docker logs -f harnessrouter
```
Open the console:
Access the web console at http://localhost:3000 and sign in with the default username harnessrouter and password harnessrouter. Remember to change the default password immediately for security.
Connect a model provider:
In the console, go to "Bring Your Own Key", add an integration, choose a provider, and enter your API key. This makes its models available for tasks.

For detailed setup, including custom configurations and upgrades, refer to the official documentation.

Examples

Once HarnessRouter is set up and a model provider is connected, you can start running tasks.

Running a task in the Console: Navigate to "Agent harnesses", select a supported harness, and choose "New task". Provide the agent with a concrete task, select an available model, and observe the live progress. You can also review files produced within the same session.

Integrating with your product backend via API: HarnessRouter provides an OpenAI Responses-compatible API for seamless integration into your product.

Create an API key:
In the Console, go to "API Keys" and create a new API key. Store this secret securely as HARNESSROUTER_API_KEY in your backend.

Call the API:

Use curl or your preferred HTTP client to interact with the API, specifying the harness_id and model.

export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness

curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
  -H 'content-type: application/json' \
  -d '{
    "input":"Reply with exactly: it works.",
    "metadata":{"harness_id":"codex"},
    "model":"gpt-5.4-mini",
    "stream":false
  }'

The full API documentation is available at $HARNESSROUTER_BASE_URL/v1/openapi.json and a browsable version at /v1/docs.