HarnessHub

One API for every agent harness. Self-hosted, open, and built for teams shipping agent products.

Visit HarnessHub · Report an issue · Join the discussion

HarnessHub gives your product one consistent interface for coding and agent harnesses. Connect multiple runtimes behind a single API, keep execution on infrastructure you control, and switch backends without rebuilding your product integration.

Why HarnessHub

• One integration — start tasks, continue sessions, stream progress, manage files, cancel work, and inspect structured failures through one API.
• Pluggable harnesses — select the backend per task instead of coupling your product to one runtime.
• Open and self-hosted — bring your own provider keys and run the stack on infrastructure you control.
• Built for product teams — use an OpenAI Responses-compatible surface and keep harness engineering out of your application.
• Unified Harness Protocol — an open protocol for consistent agent lifecycle behavior across implementations.

Quickstart

Run with Docker

Build the image locally, then start the service:

docker build -t harnesshub .
docker run -d --name harnesshub \
  -p 127.0.0.1:3000:3000 \
  -v harnesshub:/data \
  harnesshub

Open http://localhost:3000 after the container reports that it is ready. Connect a model provider in the console, choose a harness, and start your first task.

Keep the initial instance local and change the default console credentials before exposing it to a network.

For Compose, upgrades, backups, provider configuration, and production networking, see the guides in the docs directory.

Use the API

Create an API key in the console, store it on your server, and call the OpenAI Responses-compatible endpoint:

export HARNESSHUB_BASE_URL=http://localhost:3000/api/harness
export HARNESSHUB_API_KEY=your_api_key

curl --fail-with-body -sS "$HARNESSHUB_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $HARNESSHUB_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
  }'

Set the stream field to true to receive server-sent events. Use previous_response_id to continue a session and attach files or retrieve generated artifacts through the same lifecycle.

Architecture

HarnessHub separates product-facing API concerns from harness execution:

1. Gateway — presents a stable API for products and clients.
2. Session layer — keeps task state, transcripts, files, and artifacts together.
3. Harness runners — execute supported agent runtimes as replaceable backends.
4. Protocol and conformance — define portable behavior across harness implementations.

Explore the implementation in the server, runner, and protocol directories.

Development

The project is primarily Python with supporting JavaScript, TypeScript, shell, and Docker tooling. Start with the contributor documentation and the focused test suites:

• CONTRIBUTING.md
• docs/
• runner/tests/
• protocol/conformance/

Upstream and license

HarnessHub is an independently branded distribution of the Apache-2.0 HarnessRouter Community Edition. This repository preserves the upstream license and attribution requirements; see LICENSE before redistributing or modifying the project.

• Upstream project: HarnessRouter/harnessrouter
• Website: harnesshub.web.id

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.