The world’s first unified interface for agent harnesses.

Build agent products without handling harness engineering.

Plug Codex, Claude Code, Hermes, DeepSeek Harness, and more into your product as agent backends.
One API for them all.

Quickstart · API · Starter kits · Cloud

N × M harness integrations → 1 unified interface.

Compare and switch harnesses. Optimize cost and latency.

HarnessRouter is the unified interface for agent harnesses. Community Edition lets you self-host it under Apache 2.0, with the Console, Gateway, and Runner in one Docker deployment. It implements the Unified Harness Protocol (UHP) on infrastructure you control.

Run locally → · Prefer managed agent harnesses? Explore HarnessRouter Cloud →

Quickstart

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.

Existing installation or custom setup

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.

Console not ready or a harness missing?

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:

Username	harnessrouter
Password	harnessrouter

Warning

Change the default password in Profile. Keep the instance local until you change it. Saving briefly restarts the Console and signs out other browsers.

See the sign-in screen

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 Integrations → Add Integration. Choose a provider, give the integration a name, and add 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.

See the provider setup screen

5. Run your first task

Open Agent harnesses, choose a supported harness, and select New task. Pick an available model and give the agent a concrete task. Follow live progress and open the files it produces in the same session.

_{In the illustrative run above, Hermes reviews a fictional NDA and produces a redlined version, a clean copy, and a negotiation memo.}

Configure a custom harness (optional)

Built-in harnesses work without this step. Create a custom harness when you want reusable behavior tailored to your product.

1. Create. Select New harness in Agent harnesses. In Add harness, set the Name, Base harness, and Default model together, then select Create and configure.
2. Customize. In Harness Settings, add Agent instructions, configure Tools (use Add MCP for an optional MCP server), and add Skills as needed.
3. Save and test. Select Save Changes, then Run Task to test the saved configuration.

You can change the default model later in Settings, but the base harness cannot be changed after creation.

Watch the configuration walkthrough · 48 seconds

_{Configure DeepSeek Harness for customer-feedback analysis.}

Integrate your harness into your product backend with one API

Run product tasks with built-in or custom harnesses as pluggable agent backends. Call your self-hosted instance’s OpenAI Responses-compatible API and select the harness with metadata.harness_id. No Cloud deployment is required.

Once your harness runs successfully in the Console:

1. Open /keys on the same CE instance (default local address) and choose Create API key. Open this URL directly if API keys is not visible in the sidebar.
2. Store the secret shown once as HARNESSROUTER_API_KEY in your product backend. Never expose it in browser code. This CE-issued key is separate from your Console password and provider key.
3. Call the API with the Harness ID shown in the Console and a model served by your connected provider.

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 task and its transcript appear in the same workspace in the Console. Set "stream": true to receive server-sent events.

The default URL works when your backend and CE run on the same computer. From another machine or container, use a reachable URL for the CE instance. Read the complete self-hosted API and networking guide →

Your application can…	How
Start tasks	Send instructions and check execution status
Continue sessions	Send follow-up instructions with previous_response_id
Stream progress	Receive live updates as the agent works
Work with files	Attach input files and retrieve generated outputs
Cancel tasks	Stop work that is no longer needed
Inspect execution	Review structured errors and execution traces

See where agent harnesses fit in your product

Build beyond coding: explore harness-powered presentations, spreadsheets, dashboards, and videos.

Slides An agent harness creates slides from your brief; you edit the text, layout, and style on the canvas.	Sheets An agent column runs a harness-backed agent for each row, using preceding columns as input and filling cells with results. Requires another agent for the agent column.
Dashboards An agent harness reads your database schema and writes SQL for charts; the dashboard refreshes queries when opened. Requires a database connection.	Videos An agent harness plans shots and uses video tools to generate clips; you edit them on a timeline and export the film. Video generation has additional per-clip costs.

Explore the Starter Kits repository →

Starter Kits have separate licensing terms from Community Edition.

Before launching a kit

Open Starter Kits in the Console. Select a harness and model supported by your connected providers.

Dashboards: use a reachable database and a read-only database account. Set HR_SECRET_KEY to encrypt stored connections, and review the sample-row setting before connecting.

Read the kit setup guide →

Deployment choices

Self-host for control

• Your infrastructure. One Docker deployment for the Console, Gateway, and Runner.
• Your credentials and state. Provider keys, sessions, files, and workspaces stay under your control. Model requests still go to your configured provider.
• Real workspaces. Native filesystem, shell, and Git workflows, with separate session workspaces.
• No Console product analytics. Community Edition disables the Console analytics pipeline.

Choose your path to Cloud

Choose HarnessRouter Cloud for managed deployment, maintenance, and scaling, with tasks running in serverless, isolated sandboxes through the same API contract.

Local → Cloud	Start directly in Cloud
Bring a custom harness you’ve configured locally. Follow the upload guide →	Create and run harnesses without a local deployment. Open HarnessRouter Cloud →

For local uploads: set HR_SECRET_KEY on your local instance to encrypt the saved destination key. Save your custom harness in Settings, select Upload to Cloud, then connect a destination using its Cloud workspace API key.

Uploads copy harness configuration, not provider keys, sessions, or generated files. Uploading again replaces that destination’s hosted copy.

Inside Community Edition

┌─ HarnessRouter container ─────────────────────────────────┐
│  Console :3000   ← only published port                    │
│       │ same-origin proxy                                 │
│       ▼                                                   │
│  Gateway :8080   Responses API + harness lifecycle        │
│       │ loopback                                          │
│       ▼                                                   │
│  Runner  :8081   runs harnesses in session workspaces     │
│                                                           │
│  /data volume   database · files · secrets · workspaces   │
└───────────────────────────────────────────────────────────┘

The Gateway and Runner listen on loopback inside the container. Sessions use separate workspaces and operating-system users, not separate containers. The Console is the entry point for both UI and API.

See configuration, upgrades and backups, and public deployment with TLS.

The Unified Harness Protocol

Unified Harness Protocol (UHP) is the public, versioned contract implemented by Community Edition and HarnessRouter Cloud. Its task surface is deliberately compatible with the OpenAI Responses API, so existing Responses SDKs, streaming parsers, and UI components can work with a UHP server. UHP defines harness execution semantics for harness selection, persistent sessions, files, cancellation, and harness-managed tools and skills.

This repository contains the Apache 2.0 reference implementation, machine-readable schemas, and the conformance suite.

Resource	Purpose
Specification	Normative protocol behavior
OpenAI Responses compatibility	Compatibility with existing OpenAI Responses API clients
OpenAPI and JSON Schema	Machine-readable contracts
Conformance suite	Testable compatibility requirements
Governance	How the standard evolves

Resources

Goal	Resources
Build	Cloud & integration docs · API guide · Starter kits
Deploy	Setup & operations · Local → Cloud · HarnessRouter Cloud
Protocol	Unified Harness Protocol (UHP)
Community	Discord · LinkedIn · X · Contributing · Security

Star History

License

HarnessRouter Community Edition is licensed under Apache 2.0. Agent harness CLIs are installed on first launch and remain subject to their respective upstream licenses. See NOTICE for third-party notices and the Starter Kits repository for its separate licensing terms.