Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

docs: sharpen README positioning and integration guide (#154)

github-actions[bot]69caeffaf3f3
diff --git a/README.md b/README.md
index 08c478ba..cdbd924c 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,5 @@
<p align="center">
- <picture>
- <source media="(max-width: 600px)" srcset="docs/images/2026-09-10-readme-category-banner-mobile.svg">
- <img src="docs/images/2026-09-10-readme-category-banner-desktop.svg" width="100%" alt="The world’s first unified interface for agent harnesses.">
- </picture>
+ <strong>The world’s first unified interface for agent harnesses.</strong>
</p>
<h1 align="center">
@@ -22,7 +19,7 @@
</p>
<p align="center">
- <a href="#top" title="Back to the top to star this repository"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FHarnessRouter%2Fharnessrouter&amp;query=%24.stargazers_count&amp;label=Stars&amp;logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNCIgaGVpZ2h0PSIxNCIgdmlld0JveD0iMCAwIDE2IDE2Ij48cGF0aCBmaWxsPSIjZTNiMzQxIiBkPSJNOCAuMjVhLjc1Ljc1IDAgMCAxIC42NzMuNDE4bDEuODgyIDMuODE1IDQuMjEuNjEyYS43NS43NSAwIDAgMSAuNDE2IDEuMjc5bC0zLjA0NiAyLjk3LjcxOSA0LjE5MmEuNzUuNzUgMCAwIDEtMS4wODguNzkxTDggMTIuMzQ3bC0zLjc2NiAxLjk4YS43NS43NSAwIDAgMS0xLjA4OC0uNzlsLjcyLTQuMTk0TC44MTggNi4zNzRhLjc1Ljc1IDAgMCAxIC40MTYtMS4yOGw0LjIxLS42MTFMNy4zMjcuNjY4QS43NS43NSAwIDAgMSA4IC4yNVoiLz48L3N2Zz4%3D&amp;color=e3b341&amp;style=flat&amp;cacheSeconds=300&amp;labelColor=444c56" alt="GitHub Stars, exact count" title="Back to the top, then click GitHub’s Star button. Dynamic count; updates may be cached."></a>
+ <a href="#top" title="Back to the top to star this repository"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2FHarnessRouter%2Fharnessrouter&amp;query=%24.stargazers_count&amp;label=Stars&amp;logo=github&amp;logoColor=white&amp;color=e3b341&amp;style=flat&amp;cacheSeconds=300&amp;labelColor=444c56" alt="GitHub Stars, exact count" title="Back to the top, then click GitHub’s Star button. Dynamic count; updates may be cached."></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-285AFF?logo=apache&amp;logoColor=white&amp;style=flat&amp;labelColor=444c56" alt="License: Apache 2.0"></a>
<a href="https://hub.docker.com/r/harnessrouter/harnessrouter"><img src="https://img.shields.io/docker/pulls/harnessrouter/harnessrouter?style=flat&amp;logo=docker&amp;logoColor=white&amp;label=Docker+pulls&amp;labelColor=444c56&amp;color=285aff" alt="Docker pulls"></a>
<a href="protocol/conformance"><img src="https://img.shields.io/badge/UHP-Full-16824B?style=flat&amp;labelColor=444c56" alt="UHP conformance: Full"></a>
@@ -42,39 +39,25 @@
<a id="one-integration"></a>
-## N × M harness integrations → 1 unified interface.
+<br>
-N harnesses × M integration responsibilities. Connect your product once; HarnessRouter handles the harness-specific differences.
+## N × M harness integrations → 1 unified interface.
-![Animated illustration: compare four generic harnesses and 4 × 9 = 36 repeated responsibilities with one HarnessRouter product integration. Add a fifth harness in With while product integration stays one, then return to Without to see 5 × 9 = 45. With names Codex, Claude Code, Hermes, Pi, and DeepSeek Harness.](docs/images/2026-09-10-harnessrouter-integration-comparison-v4.gif)
+<img src="docs/images/2026-09-10-harnessrouter-integration-comparison-v4.gif" width="100%" alt="Animated illustration: compare four generic harnesses and 4 × 9 = 36 repeated responsibilities with one HarnessRouter product integration. Add a fifth harness in With while product integration stays one, then return to Without to see 5 × 9 = 45. With names Codex, Claude Code, Hermes, Pi, and DeepSeek Harness.">
<a id="one-interface-the-freedom-to-choose"></a>
+<br>
+
## Compare and switch harnesses. Optimize cost and latency.
-<a href="https://harnessrouter.ai/benchmarks" title="In many cases, we’ve seen over 90% cost savings. Lower cost doesn’t always mean slower runs.">
+<a href="https://harnessrouter.ai/benchmarks" title="Open the methodology. The cost and latency figures compare separate extremes; results vary by task.">
<picture>
<source media="(max-width: 600px)" srcset="docs/images/benchmark-summary-mobile.svg">
- <img src="docs/images/benchmark-summary.svg" width="100%" alt="One recorded task, eight Harness × Model configurations. Save 99.8%, lowest vs. highest cost: 0.47–223 credits. 3.2× faster, fastest vs. slowest run: 1m 25s–4m 36s end to end. Cost and latency vary by task. See the benchmark.">
+ <img src="docs/images/benchmark-summary.svg" width="100%" alt="One recorded task, eight Harness × Model configurations. Save 99.8%, lowest vs. highest cost: 0.47–223 credits. 3.2× faster, fastest vs. slowest run: 1m 25s–4m 36s end to end. These are separate comparisons; results vary by task. Open the methodology.">
</picture>
</a>
-<details>
-<summary>Benchmark data and comparison basis</summary>
-
-One recorded Care Prep task, eight Harness × Model configurations.
-
-| Metric | Observed range | Comparison |
-|---|---|---|
-| Cost | 0.47–223 credits | 99.8% lower, lowest vs. highest cost |
-| End-to-end latency | 1m 25s–4m 36s | 3.2× faster, fastest vs. slowest run |
-
-These compare separate extremes, not one configuration delivering both improvements. Results are specific to this task, not a universal ranking.
-
-[Recorded results and methodology →](https://harnessrouter.ai/benchmarks)
-
-</details>
-
<a href="#top" title="Back to the top to star this repository">
<picture>
<source media="(max-width: 600px)" srcset="docs/images/github-readme-star-cta-mobile.svg">
@@ -82,12 +65,14 @@ These compare separate extremes, not one configuration delivering both improveme
</picture>
</a>
-**HarnessRouter Community Edition** is the self-hosted, Apache 2.0 edition of the **unified interface for agent harnesses**. It implements the [Unified Harness Protocol (UHP)](https://unifiedharnessprotocol.org), with the Console, Gateway, and Runner in one Docker deployment on infrastructure you control.
+**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)](https://unifiedharnessprotocol.org) on infrastructure you control.
-[Run locally →](#quickstart) · [Prefer managed execution? Explore Cloud →](https://harnessrouter.ai)
+[Run locally →](#quickstart) · [Prefer managed agent harnesses? Explore HarnessRouter Cloud →](https://harnessrouter.ai)
<a id="install"></a>
+<br>
+
## Quickstart
Start with one Docker command, wait for the first launch, then connect a model provider and run your first task.
@@ -161,11 +146,13 @@ Open [http://localhost:3000](http://localhost:3000), or your chosen host port, a
Using an existing volume or custom credentials? [Check credential precedence and setup](docs/self-hosting-guide.md#install).
+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.
-Model requests use the provider and credentials you choose.
+This provider key authorizes model requests. It is separate from the HarnessRouter API key used for product integration below.
<details>
<summary>See the provider setup screen</summary>
@@ -209,18 +196,27 @@ You can change the default model later in Settings, but the base harness cannot
<a id="use-the-api-directly"></a>
-## Integrate into your product with one API
+<a id="integrate-into-your-product-with-one-api"></a>
+
+<a id="integrate-into-your-product-backend-with-one-api"></a>
+
+<br>
+
+## Integrate your harness into your product backend with one API
-With HarnessRouter running, connect your product to the same OpenAI Responses-compatible API used by the Console.
+Treat each harness as a pluggable agent backend for your product. Integrate a built-in or custom harness through your self-hosted HarnessRouter instance’s OpenAI Responses-compatible API. `metadata.harness_id` selects the harness that runs each agent task, so you can switch harnesses without redesigning your product backend. No Cloud account or upload is required.
-Sign in once to keep a local session cookie, then run a turn. To use your custom harness, replace `metadata.harness_id` with its **Harness ID**.
+Once your harness runs successfully in the Console:
+
+1. Open `/keys` on the same CE instance ([default local address](http://localhost:3000/keys)) and choose **Create API key**. This key is created in and used by your self-hosted CE instance; it is not a Cloud key. CE currently hides this page from the sidebar, so open the URL directly.
+2. Store the secret shown once as `HARNESSROUTER_API_KEY` in your product backend. Never expose it in browser code.
+3. Call the API with the Harness ID shown in the Console and a model served by your connected provider.
```bash
-curl -s -c hr.cookies http://localhost:3000/api/selfhost/login \
- -H 'content-type: application/json' \
- -d '{"username":"harnessrouter","password":"<your-password>"}'
+export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness
-curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
+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.",
@@ -230,9 +226,9 @@ curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
}'
```
-The task appears in the Console with the same session and transcript. Set `"stream": true` to receive server-sent events.
+The task and its transcript appear in the same workspace in the Console. Set `"stream": true` to receive server-sent events. This HarnessRouter API key, created in your CE instance, authenticates your product backend to that instance; it is not your Console password or model-provider key.
-Use your current username and password, adjust the port if needed, and choose a harness and model served by your connected provider.
+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 →](docs/self-hosting-guide.md#using-the-api)
<a id="one-interface-for-the-agent-lifecycle"></a>
@@ -240,7 +236,7 @@ Use your current username and password, adjust the port if needed, and choose a
<thead><tr><th scope="col">Your application can…</th><th scope="col">How</th></tr></thead>
<tbody>
<tr><th scope="row">Start tasks</th><td>Send instructions and check execution status</td></tr>
- <tr><th scope="row">Continue sessions</th><td>Send follow-up instructions within the same session</td></tr>
+ <tr><th scope="row">Continue sessions</th><td>Send follow-up instructions with <code>previous_response_id</code></td></tr>
<tr><th scope="row">Stream progress</th><td>Receive live updates as the agent works</td></tr>
<tr><th scope="row">Work with files</th><td>Attach input files and retrieve generated outputs</td></tr>
<tr><th scope="row">Cancel tasks</th><td>Stop work that is no longer needed</td></tr>
@@ -254,6 +250,8 @@ See the [API guide](docs/self-hosting-guide.md#using-the-api) for catalogs, sess
<a id="starter-kits"></a>
+<br>
+
## See where agent harnesses fit in your product
Plug agent harnesses into your own interface to power features and tasks far beyond coding. To help you explore what’s possible, we created starter kits for presentations, spreadsheets, dashboards, and videos. More kits will be added over time.
@@ -303,6 +301,8 @@ Open **Starter Kits** in the Console. Select a harness and model supported by yo
</details>
+<br>
+
## Deployment choices
<a id="why-self-host-community-edition"></a>
@@ -356,20 +356,27 @@ See [configuration](docs/self-hosting-guide.md#configuration), [upgrades and bac
<a id="unified-harness-protocol"></a>
+<br>
+
## The Unified Harness Protocol
-[Unified Harness Protocol (UHP)](https://unifiedharnessprotocol.org) is the public, versioned contract implemented by Community Edition and HarnessRouter Cloud. This repository contains the Apache 2.0 reference implementation, machine-readable schemas, and the conformance suite.
+[Unified Harness Protocol (UHP)](https://unifiedharnessprotocol.org) 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 adds the harness-specific capabilities a model API does not provide: 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.
<table>
<thead><tr><th>Resource</th><th>Purpose</th></tr></thead>
<tbody>
<tr><td><a href="protocol/versions/2026-08-11">Specification</a></td><td>Normative protocol behavior</td></tr>
+ <tr><td><a href="protocol/README.md#relationship-to-the-openai-responses-api">OpenAI Responses compatibility</a></td><td>Compatibility with existing OpenAI Responses API clients</td></tr>
<tr><td><a href="protocol/schema">OpenAPI and JSON Schema</a></td><td>Machine-readable contracts</td></tr>
<tr><td><a href="protocol/conformance">Conformance suite</a></td><td>Testable compatibility requirements</td></tr>
<tr><td><a href="protocol/GOVERNANCE.md">Governance</a></td><td>How the standard evolves</td></tr>
</tbody>
</table>
+<br>
+
## Resources
| Goal | Resources |
@@ -379,6 +386,8 @@ See [configuration](docs/self-hosting-guide.md#configuration), [upgrades and bac
| **Protocol** | [Unified Harness Protocol (UHP)](https://unifiedharnessprotocol.org) |
| **Community** | [Discord](https://discord.gg/nPcbwqVPb2) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) |
+<br>
+
## Star History
<p align="center">
@@ -391,6 +400,8 @@ See [configuration](docs/self-hosting-guide.md#configuration), [upgrades and bac
</a>
</p>
+<br>
+
## License
HarnessRouter Community Edition is licensed under [Apache 2.0](LICENSE). Agent harness CLIs are installed on first launch and remain subject to their respective upstream licenses. See [NOTICE](NOTICE) for third-party notices and the [Starter Kits repository](https://github.com/HarnessRouter/starter-kit#licensing) for its separate licensing terms.
diff --git a/docs/images/benchmark-summary-mobile.svg b/docs/images/benchmark-summary-mobile.svg
index afb73658..021c22fe 100644
--- a/docs/images/benchmark-summary-mobile.svg
+++ b/docs/images/benchmark-summary-mobile.svg
@@ -1,39 +1,38 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="360" height="416" viewBox="0 0 360 416" role="img" aria-labelledby="title desc">
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="325" viewBox="0 0 360 325" role="img" aria-labelledby="title desc">
<title id="title">Compare cost and latency across eight configurations</title>
<desc id="desc">One recorded task. Eight Harness × Model configurations. Save 99.8%, lowest vs. highest cost: 0.47–223 credits. 3.2× faster, fastest vs. slowest run: 1m 25s–4m 36s end to end. These are separate comparisons of the observed extremes. Cost and latency vary by task.</desc>
- <rect x="0.5" y="0.5" width="359" height="415" rx="8" fill="#f6f8ff" stroke="#d7e0ff"/>
+ <rect x="0.5" y="0.5" width="359" height="324" rx="8" fill="#f6f8ff" stroke="#d7e0ff"/>
<g font-family="Arial,Helvetica,sans-serif">
- <g font-size="14" font-weight="600" fill="#62626c">
- <text x="20" y="28">One recorded task</text>
- <text x="20" y="49">8 Harness × Model configurations</text>
+ <text x="20" y="25" font-size="13" font-weight="600" fill="#62626c">1 task · 8 configurations</text>
+ <g fill="none" stroke="#6385ff" stroke-width="1.3">
+ <circle cx="332" cy="22" r="7"/>
+ <path d="M332 19v4M332 25.5v.25" stroke-linecap="round"/>
</g>
<g fill="none" stroke="#62626c" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
- <g transform="translate(20 72)">
+ <g transform="translate(20 48)">
<ellipse cx="9" cy="3" rx="8" ry="3"/>
<path d="M1 3v12c0 4 16 4 16 0V3M1 9c0 4 16 4 16 0"/>
</g>
- <g transform="translate(20 217)">
+ <g transform="translate(20 178)">
<circle cx="9" cy="9" r="8.5"/>
<path d="M9 4v5l4 2"/>
</g>
</g>
<g font-size="16" fill="#62626c">
- <text x="49" y="88" font-weight="600">Cost</text>
- <text x="49" y="233"><tspan font-weight="600">Latency</tspan><tspan> · end to end</tspan></text>
+ <text x="49" y="64" font-weight="600">Cost</text>
+ <text x="49" y="194"><tspan font-weight="600">Latency</tspan><tspan> · end to end</tspan></text>
</g>
<g font-size="44" font-weight="700" letter-spacing="-1.3" fill="#285aff">
- <text x="20" y="137">Save 99.8%</text>
- <text x="20" y="282">3.2× faster</text>
+ <text x="20" y="112">Save 99.8%</text>
+ <text x="20" y="242">3.2× faster</text>
</g>
<g font-size="19" fill="#1f2328">
- <text x="20" y="167"><tspan font-weight="700">0.47–223</tspan><tspan> credits</tspan></text>
- <text x="20" y="312" font-weight="700">1m 25s–4m 36s</text>
+ <text x="20" y="141"><tspan font-weight="700">0.47–223</tspan><tspan> credits</tspan></text>
+ <text x="20" y="271" font-weight="700">1m 25s–4m 36s</text>
</g>
<g font-size="14" fill="#62626c">
- <text x="20" y="190">Lowest vs. highest cost</text>
- <text x="20" y="335">Fastest vs. slowest run</text>
- <text x="20" y="371">Cost and latency vary by task.</text>
+ <text x="20" y="163">Lowest vs. highest cost</text>
+ <text x="20" y="293">Fastest vs. slowest run</text>
</g>
- <text x="20" y="398" font-size="16" font-weight="700" fill="#0969da">See the benchmark →</text>
</g>
</svg>
diff --git a/docs/images/benchmark-summary.svg b/docs/images/benchmark-summary.svg
index bdab7cbd..94ba776f 100644
--- a/docs/images/benchmark-summary.svg
+++ b/docs/images/benchmark-summary.svg
@@ -1,36 +1,38 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="250" viewBox="0 0 960 250" role="img" aria-labelledby="title desc">
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="190" viewBox="0 0 960 190" role="img" aria-labelledby="title desc">
<title id="title">Compare cost and latency across eight configurations</title>
<desc id="desc">One recorded task. Eight Harness × Model configurations. Save 99.8%, lowest vs. highest cost: 0.47–223 credits. 3.2× faster, fastest vs. slowest run: 1m 25s–4m 36s end to end. These are separate comparisons of the observed extremes. Cost and latency vary by task.</desc>
- <rect x="0.5" y="0.5" width="959" height="249" rx="8" fill="#f6f8ff" stroke="#d7e0ff"/>
+ <rect x="0.5" y="0.5" width="959" height="189" rx="8" fill="#f6f8ff" stroke="#d7e0ff"/>
<g font-family="Arial,Helvetica,sans-serif">
- <text x="28" y="34" font-size="17" font-weight="600" fill="#62626c">One recorded task · 8 Harness × Model configurations</text>
+ <text x="28" y="29" font-size="17" font-weight="600" fill="#62626c">One recorded task · 8 Harness × Model configurations</text>
+ <g fill="none" stroke="#6385ff" stroke-width="1.3">
+ <circle cx="930" cy="24" r="8"/>
+ <path d="M930 20.5v5M930 28v.25" stroke-linecap="round"/>
+ </g>
<g fill="none" stroke="#62626c" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
- <g transform="translate(29 64)">
+ <g transform="translate(29 48)">
<ellipse cx="9" cy="3" rx="8" ry="3"/>
<path d="M1 3v12c0 4 16 4 16 0V3M1 9c0 4 16 4 16 0"/>
</g>
- <g transform="translate(509 64)">
+ <g transform="translate(509 48)">
<circle cx="9" cy="9" r="8.5"/>
<path d="M9 4v5l4 2"/>
</g>
</g>
<g font-size="18" fill="#62626c">
- <text x="58" y="80" font-weight="600">Cost</text>
- <text x="538" y="80"><tspan font-weight="600">Latency</tspan><tspan> · end to end</tspan></text>
+ <text x="58" y="64" font-weight="600">Cost</text>
+ <text x="538" y="64"><tspan font-weight="600">Latency</tspan><tspan> · end to end</tspan></text>
</g>
<g font-size="52" font-weight="700" letter-spacing="-1.6" fill="#285aff">
- <text x="28" y="136">Save 99.8%</text>
- <text x="508" y="136">3.2× faster</text>
+ <text x="28" y="116">Save 99.8%</text>
+ <text x="508" y="116">3.2× faster</text>
</g>
<g font-size="21" fill="#1f2328">
- <text x="28" y="173"><tspan font-weight="700">0.47–223</tspan><tspan> credits</tspan></text>
- <text x="508" y="173" font-weight="700">1m 25s–4m 36s</text>
+ <text x="28" y="151"><tspan font-weight="700">0.47–223</tspan><tspan> credits</tspan></text>
+ <text x="508" y="151" font-weight="700">1m 25s–4m 36s</text>
</g>
<g font-size="15" fill="#62626c">
- <text x="28" y="197">Lowest vs. highest cost</text>
- <text x="508" y="197">Fastest vs. slowest run</text>
- <text x="28" y="229">Cost and latency vary by task.</text>
+ <text x="28" y="174">Lowest vs. highest cost</text>
+ <text x="508" y="174">Fastest vs. slowest run</text>
</g>
- <text x="932" y="229" text-anchor="end" font-size="17" font-weight="700" fill="#0969da">See the benchmark →</text>
</g>
</svg>
diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.md
index aed3151f..3838bfd9 100644
--- a/docs/self-hosting-guide.md
+++ b/docs/self-hosting-guide.md
@@ -198,12 +198,15 @@ Open <http://localhost:3000>, or the host port you chose in step 2, and sign in
![The sign-in screen](images/01-login.png)
-**Change the password now**, from **Profile** in the account menu at the top right. Saving restarts
-the console, which takes about a second.
+**Change the password now**, from **Profile** in the account menu. Saving briefly restarts
+the Console.
If you set `HR_AUTH_USER` or `HR_AUTH_PASSWORD` at `docker run`, sign in with those instead — the
defaults are then refused.
+These credentials sign you into the Console. You do not need a HarnessRouter API key to run tasks
+there. Create one later when [integrating your product backend](#using-the-api).
+
<details>
<summary>Where the password lives, and what to do if you forget it</summary>
@@ -234,7 +237,7 @@ instance falls back to `HR_AUTH_USER` / `HR_AUTH_PASSWORD`.
hiding in the image.
Open **Integrations** and press **Add Integration**. It asks three things: a name, the provider,
-and your API key.
+and that provider's API key. This key authorizes model requests; it is not a HarnessRouter API key.
![Adding a provider on the Integrations page](images/05-add-integration.png)
@@ -626,22 +629,56 @@ docker build -t harnessrouter --build-arg WITH_BROWSER=1 .
## Using the API
-The console is optional: it is a thin client over the same API. On a default install that API is
-reached through the console's own port, and **the login gate covers it too**, so a call needs the
-session cookie. Sign in once and keep the cookie:
+A harness is a pluggable agent backend that runs agent tasks for your product. Integrate a built-in
+or custom harness through your self-hosted HarnessRouter instance's OpenAI Responses-compatible
+API. `metadata.harness_id` selects the harness that runs each task, so you can switch harnesses
+without redesigning your product backend. No Cloud account or upload is required.
-```bash
-curl -s -c hr.cookies http://localhost:3000/api/selfhost/login \
- -H 'content-type: application/json' \
- -d '{"username":"harnessrouter","password":"<your-password>"}'
-# {"ok":true}
-```
+Three credentials have three separate jobs:
+
+| Credential | Held by | Purpose |
+|---|---|---|
+| Console password | A person using the browser | Manage this CE instance and run tasks in its Console |
+| Provider API key | HarnessRouter | Call the model provider configured under **Integrations** |
+| HarnessRouter API key | Your product backend | Authenticate API calls to this CE instance and its workspace |
+
+For the default local installation, the API base is `http://localhost:3000/api/harness`. Use the
+host and port of the CE instance you actually started. If your backend runs on another machine
+or in another container, `localhost` refers to that caller, not automatically to HarnessRouter.
+The default Docker command publishes port 3000 only on the host's loopback interface. Keep that
+default for same-machine development. For remote callers, deliberately make the instance reachable
+through a trusted network or reverse proxy and use HTTPS; see [Putting it on a public URL](#putting-it-on-a-public-url).
-Use your current username and password and adjust the host port if changed. Then run a turn with
-a harness and model served by your connected provider. The gateway speaks the Responses API:
+Before wiring in a product, connect a provider and run one task in the Console with the harness and
+model you intend to call. That verifies the execution path before adding network and backend-auth
+variables. It is a setup check, not a technical prerequisite for the API.
+
+### Create a key on this CE instance for your backend
+
+1. Sign in to the Console of the CE instance your product will call, then open `/keys` on that same host and port ([default local address](http://localhost:3000/keys)). Community Edition currently hides this page from the sidebar, so use its URL directly.
+2. Confirm the workspace containing the harness, then select **Create API key**. Give it a name and select **Create key**.
+3. Copy the secret shown once. Store it in your product backend's secret store or environment. The examples call this variable `HARNESSROUTER_API_KEY`.
+
+The key is scoped to the selected workspace and can be rotated or revoked on the same page.
+It is created in this self-hosted instance and authenticates requests to that CE deployment. It is
+neither a Cloud key, your Console password, nor the model-provider key configured
+in **Integrations**. Never put it in browser-side code or commit it to Git.
+
+### Run a task
+
+This example assumes `HARNESSROUTER_API_KEY` is already set. Choose an installed harness and a
+model served by your connected provider. For a custom harness, use its **Harness ID** as
+`metadata.harness_id`.
+
+Set the base URL to the CE instance as seen by your backend. Creating a task requires **POST**. The
+command below supplies a request body, so curl uses POST; opening the endpoint in a browser's
+address bar sends GET and does not run a task.
```bash
-curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
+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 this and nothing else: it works.",
"metadata":{"harness_id":"codex"},
@@ -661,20 +698,52 @@ curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
"metadata":{"session_id":"hsessa79756fab07a4bf58fa072be24d5ce59"}}
```
-That turn is not a side channel: it appears in the console under **Tasks**, against the same
-harness, with its full transcript. The console and the API are the same instance seen twice.
+The task and its transcript appear in the key's workspace in the same Console. API calls
+authenticate with the key alone: your backend does not need to log in with a password or maintain
+a Console session cookie. Your application's own user authentication and authorization remain
+your responsibility.
<details>
<summary>The rest of the surface</summary>
-`harness_id` accepts one of the built-in ids the console shows on the Harnesses page: `codex`,
-`claude-code`, `hermes`, or the id of a harness you created. Harness CRUD (`/v1/harnesses`), the
-model catalog (`/v1/models`), sessions (`/v1/sessions/{id}/turns`, `/cancel`) and task listing
-(`/v1/traces`) are all on the same prefix. Set `"stream":true` for server-sent events instead of
-one response at the end.
+All paths below are relative to the API base above and use the same Bearer key.
+
+| Action | API operation |
+|---|---|
+| Discover harnesses and models | `GET /v1/harnesses`, `GET /v1/models` |
+| Start a task or continue a session | `POST /v1/responses`; set `previous_response_id` to continue a previous turn |
+| Check a response | `GET /v1/responses/{response_id}` |
+| Stream progress | Set `"stream": true` on the response request for server-sent events |
+| Read session history | `GET /v1/sessions/{session_id}/turns` |
+| Upload inputs or retrieve outputs | `POST /v1/files`; `GET /v1/sessions/{session_id}/files` |
+| Cancel work | `POST /v1/responses/{response_id}/cancel` |
+| Inspect execution | `GET /v1/traces/{session_id}` and `/v1/traces/{session_id}/events` |
+
+For file attachment and download formats, see the [UHP specification](https://unifiedharnessprotocol.org/spec).
+
+</details>
+
+<a id="console-session-auth"></a>
+
+<details>
+<summary>Optional: use a Console session for local debugging</summary>
+
+The Console uses a session cookie. You can also use that session from a local terminal when
+debugging. This is also supported by self-hosted CE; it is not a Cloud-only flow. The cookie can
+authenticate task requests to `POST /v1/responses` as well as the model-list request below.
+It is not required for API-key authentication or recommended as your product's backend credential.
+
+```bash
+curl --fail-with-body -sS -c hr.cookies http://localhost:3000/api/selfhost/login \
+ -H 'content-type: application/json' \
+ -d '{"username":"harnessrouter","password":"<your-password>"}'
+
+curl --fail-with-body -sS -b hr.cookies http://localhost:3000/api/harness/v1/models
+```
-If the box is one nobody else can reach, `HR_AUTH_DISABLED=1` removes the gate entirely and the
-same calls work with no cookie at all.
+Use your current Console credentials, not the initial defaults if you changed them. Treat
+`hr.cookies` as a secret, do not commit it, and remove it when finished. Keep authentication enabled;
+you do not need `HR_AUTH_DISABLED=1` to integrate your backend.
</details>