# HarnessRouter: Unified Interface for AI Agent Harnesses

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/harnessrouter-harnessrouter
Generated for open source discovery and AI-assisted research.

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.

GitHub: https://github.com/HarnessRouter/harnessrouter
OSRepos URL: https://osrepos.com/repo/harnessrouter-harnessrouter

## 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.

## Topics

- AI Agents
- Agent Framework
- LLM
- Open Source
- Self-Hosted
- Unified API
- Python
- AI Infrastructure

## Repository Information

Last analyzed by OSRepos: Tue Sep 22 2026 17:55:16 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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.

1.  **Start HarnessRouter:**
    bash
    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.

2.  **Wait for the first launch:**
    Monitor the logs until you see `[harnessrouter] ready on :3000`.
    bash
    docker logs -f harnessrouter
    

3.  **Open the console:**
    Access the web console at [http://localhost:3000](http://localhost:3000) and sign in with the default username `harnessrouter` and password `harnessrouter`. Remember to change the default password immediately for security.

4.  **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.

1.  **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.

2.  **Call the API:**
    Use `curl` or your preferred HTTP client to interact with the API, specifying the `harness_id` and `model`.
    bash
    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`.

## Links

*   [Official GitHub Repository](https://github.com/HarnessRouter/harnessrouter)
*   [HarnessRouter Cloud & Integration Docs](https://harnessrouter.ai/docs)
*   [Unified Harness Protocol (UHP)](https://unifiedharnessprotocol.org)
*   [Join the Community (Discord)](https://discord.gg/nPcbwqVPb2)
*   [Starter Kits Repository](https://github.com/HarnessRouter/starter-kit)