HarnessRouter Community Edition
What belongs to UHP, what is specific to HarnessRouter, and what the current self-hosted reference implementation supports.
Page reviewed 22 Nov 2026 Source and review policy
Choose the smallest deployment you can verify
Section titled “Choose the smallest deployment you can verify”Treat installation, backend readiness and application acceptance as three separate checkpoints. The stable operations guide explains that the persistent /data volume holds both durable product state and the agent CLIs installed at first start. Updating an image while reusing that volume does not establish which executable is actually running.
| Checkpoint | Evidence to capture | If it fails |
|---|---|---|
| Service starts | Release/image identity, readiness log and console access | Inspect startup/install errors before changing client requests |
| Selected backend is usable | Installed executable version, available harness/model and provider route | Repair that backend or credential route; another working backend is not equivalent evidence |
| Product workflow works | Submitted Response, terminal state, continuation and retrieved file | Keep the response/session identifiers and diagnose the failed lifecycle step |
For a first integration, enable one backend and one authenticated provider route, then use the API example below. Add Runtime Plugins only after that baseline works; add Environments when repeated project/dependency setup is the measured problem. This sequence makes a failed first turn diagnosable: service startup, provider authentication and optional connected services no longer change together.
Keep a volume backup and the previous image coordinate before upgrading. Read the documented restart procedure rather than deleting the volume to force a CLI reinstall. Your acceptance record should name the installed version even when the entrypoint’s default selects latest.
Release scope checked 19 November: stable is v0.41.24 / 93994cfcea54. Upstream main was checked separately at d37066534ffc, one commit ahead of the tag. The release list still contains the superseded v0.37.0-rc.1 through rc.4 and v0.37.4-rc.1 candidates, but prerelease numbering does not replace the stable/Latest coordinate. The table below reports the stable implementation.
HarnessRouter Community Edition is the self-hosted reference implementation of UHP. Reference implementation behavior is not automatically normative UHP behavior.
Run a first self-hosted task
Section titled “Run a first self-hosted task”The v0.29.1 quickstart requires Docker, about 4 GB of disk and a provider API key. The example below is source-checked and unexecuted here; it creates a container and persistent data volume when you run it.
docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ harnessrouter/harnessrouterdocker logs -f harnessrouterKeep the initial service on loopback. Wait for the documented readiness message, then open the console, change the initial credentials and connect a model provider. First launch installs the enabled harness CLIs; a reachable console alone does not prove every backend installed successfully. Inspect the available-backend log and catalogue.
| Credential | What it authorizes |
|---|---|
| Console login | Administrative access to the CE instance |
| Provider API key | Model requests through the selected provider |
| CE-issued API key | Your product’s calls to this HarnessRouter instance |
The self-hosted API guide uses the local base URL http://localhost:3000/api/harness. Create the CE key in the console, keep it on your backend, and select a real harness ID and a model available through your configured provider. The upstream README’s example is:
export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harnesscurl --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 }'This can incur provider usage. codex and gpt-5.4-mini are the upstream example values, not a promise that they exist or are enabled on every installation. A provider key is not a substitute for the CE key. From another container or host, localhost addresses that caller; use the reachable CE URL described in the networking guide.
Acceptance before depending on a backend
Section titled “Acceptance before depending on a backend”Check one task, its terminal output, session continuation, required tool calls and artifact retrieval. Then exercise a denied operation and a lost/expired session. Record the server release, installed backend version and model/provider route. The conformance suite tests protocol behavior; it does not guarantee every upstream feature or provider account works.
The quickstart image command follows upstream and is not version-pinned. For reproducible deployment, use the version-pinning and backup procedure in the self-hosting guide; pulling an image does not replace a running container.
Current implementation snapshot
Section titled “Current implementation snapshot”| Coordinate | Current state |
|---|---|
| Stable release | v0.38.2 — a minor line: v0.38.0 keeps MCP credentials out of the session, encrypts stored credentials at rest on every install, and lets a task end by asking the person (incomplete_details.reason input_required); v0.38.1 closes a group-root reach gap and makes a task that cannot start say why; v0.38.2 corrects the image’s licensing. It publishes the release line that keeps UHP 2026-10-19 (the new model_unavailable error and the harness_retirement / input_history / harness_idempotency capabilities) in the product, together with the F-09 retirement check and the F-10 idempotency check, adds four harness bases in v0.37.0 and has shipped eleven further stable releases since v0.37.10 — v0.37.11 at 17:15:36 UTC, v0.37.12 at 18:50:37 UTC on 29 October, v0.37.13 at 04:38:37 UTC on 31 October, v0.37.14 at 10:24:02 UTC on 1 November, v0.37.15 at 03:16:52 UTC, v0.37.16 at 11:35:34 UTC and v0.37.17 at 23:16:12 UTC on 3 November, v0.37.18 at 01:41:17 UTC on 4 November, and the minor line v0.38.0 at 07:28:26 UTC, v0.38.1 at 17:29:58 UTC and v0.38.2 at 22:53:50 UTC on 4 November |
| Stable commit | 8e1cf1b598a7ea864fda3a5de064b11289b6ac84 |
Upstream main | Checked at 46d2cc2167ea, two commits ahead of the stable tag — both narrowing a turn’s reach to the session that started it |
| UHP protocol advertised by CE | 2026-10-04 Draft — gateway/app.py sets UHP_VERSION = "2026-10-04" at v0.41.24 and on main, so the served version string moved forward but still lags the published 2026-10-19 draft. The v0.35.5 through v0.41.24 releases nevertheless implement the 2026-10-19 additions, and the conformance suite at that tag targets 2026-10-19 |
| Optional capabilities advertised by CE | input_history: true from v0.36.0 — UHP_CAPABILITIES in gateway/app.py carries it, and GET /v1/uhp and GET /v1/bases report it. harness_idempotency: true from v0.37.11, which reports it whenever a control store is available, as self-hosted installs always have. input_requests: true from v0.38.0. memories: true and session_branching: true from v0.40.0 and v0.39.0, and resume: true from v0.41.0 — so the optional Memories chapter, the branching surface and the interrupted-turn resume are now all advertised. The optional harness_retirement capability is still not advertised, so that one remains not established in the reference implementation. No conformance check exercises input_history; the F-10 check skips a server that does not report harness_idempotency. |
| Conformance package | 2026.10.19.post5 |
| Executable checks | 104 |
| Released backends | 30 offered |
Relay streaming and upstream liveness in v0.29.1
Section titled “Relay streaming and upstream liveness in v0.29.1”v0.29.1 fixes two operator-visible relay failure modes without changing UHP, the conformance package or the 20-backend set. The provider stream is now forwarded with read1 as bytes arrive instead of waiting for a 4 KB block or end-of-stream. The relay also measures provider events, not socket activity alone: comment-style keep-alive lines no longer prevent HR_RELAY_UPSTREAM_TIMEOUT_S (600 seconds by default) from reporting an upstream that has stopped producing events. The DeepSeek Harness relay applies the same rules.
The release and PR #381 say these defects were reproduced with tests driving the real handlers over real sockets, not on a live provider. They also distinguish a different failure mode that remains intentionally unfixed here: a model can keep emitting reasoning events after its answer, which is activity rather than a stalled upstream. For an upgrade check, measure first-event latency and a keep-alive-only stall separately from a continuously emitting model.
Release train highlights
Section titled “Release train highlights”v0.24.0/ PR #266: introduces Runtime Plugins, starting with a Browser service connected once per workspace and included explicitly per harness.v0.25.0/ PR #264: adds CheetahClaws 3.5.88 as backend sixteen.v0.26.x: implements UHP Environments, including builds, versions, read-only session mounts, capability discovery and conformance coverage.v0.26.18/ PRs #350-#351: adds Claude Sonnet 5.5 across the applicable model catalogue and removes the separate per-organization Runtime Plugin availability gate. The default was already open to every organization, so existing default instances do not change behavior.v0.27.0/ PR #343: adds a Microsoft 365 Runtime Plugin using each organization’s own Entra application. Delegated mode executes as the signed-in workspace member instead of borrowing another member’s identity.v0.28.6/ PR #368: hardens public artifact sharing with sandboxed response headers and durable revocation revalidation on the next read.v0.28.7/ PR #369: adds GPT-6.1 Sol to every harness base that carries GPT-6 Sol, with the release recording connection-specific measured coverage and explicit refusal notes where a channel does not serve the model.v0.29.1/ PR #381: forwards relay streams as data arrives, reports event-level upstream silence despite keep-alive lines, applies the same liveness rules to the DeepSeek Harness relay, and fixes RC publication so prereleases do not take GitHub’s Latest badge. Backend count, UHP and conformance coordinates are unchanged.v0.29.0/ PR #373: adds Kilo CLI 7.8.1, MiniMax Code 0.5.4, Grok Build 1.0.41 and Agent Zero v2.13 as four new bases. The same release hardens relay failure/retry handling and keeps credential-bearing harness configuration out of checkpoints/workspace repositories.
None of these later product/model changes revise the UHP protocol version.
Runtime Plugins are not UHP Harness Plugins
Section titled “Runtime Plugins are not UHP Harness Plugins”HarnessRouter Runtime Plugins are workspace-connected runtime services. Browser and Microsoft 365 are current implementation examples.
UHP Harness Plugins are protocol-level Agent Plugins packages carried on harness objects. The two concepts have different ownership, transport and lifecycle boundaries.
Backend set
Section titled “Backend set”The released backend set is now 30:
Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Gemini CLI, Oh My Pi, Goose, Kimi Code CLI, Aider, OpenHands, System One, CheetahClaws, Kilo CLI, MiniMax Code, Grok Build, Agent Zero, MiMo Code, jcode, OpenSquilla, nanobot, Qoder Cloud Agent, ZeroClaw, Mistral Vibe, Docker Agent, fast-agent and Deep Agents Code.
The runner’s BACKENDS registry now holds 31 bases and the product’s default HR_BACKENDS set 30, so the count above is the number of bases the product actually offers by default. Roder is the difference: v0.39.0 added it to the registry and to the catalogue, but it is opt-in, so it is installed only where an operator adds roder to HR_BACKENDS. That is a change in kind as well as in number: the previous stable implemented Gajae-Code and pinned it with its own tests, but listed, routed and ran it nowhere — a product write-wall, not a defect — and v0.37.0 removed that entry from the registry while adding Mistral Vibe, Docker Agent, fast-agent and Deep Agents Code. The registry was re-read at v0.41.24 on 19 November 2026 and holds 31 entries — the five releases since v0.37.8 changed model coverage, relay behaviour, the harness-create contract and the starter-kit naming, not the set of bases.
Adapter support does not establish native UHP adoption by the upstream project.
Model coverage is decided per base and per connection
Section titled “Model coverage is decided per base and per connection”A base offers only the models it was measured to run, on the connection the reader actually uses. The release matrix measures a first turn, a follow-up, a model switch, a file, and a conversation continued after its sandbox restarted, and a base offers a model only where it passed all of it. The result is a per-base catalogue rather than one list of models for the product, and the same model can be offered on one base and withheld on another.
The transport a base speaks decides part of it. Deep Agents Code runs over the Responses API, so it defaults to gpt-6.1-sol as Codex, Hermes, Pi and OpenCode already do. Mistral Vibe, Docker Agent and fast-agent speak chat/completions, and OpenAI, Azure OpenAI and TokenRouter refuse gpt-6.1-sol there when the request carries function tools, so those three keep gpt-5.4 on those connections and run gpt-6.1-sol through OpenRouter and Vercel, which reach it over the Responses API.
Image capability is a property of the model rather than of the base, and it is now carried per turn. A conversation’s images are fitted to what the current model takes: a text-only model receives none, every image left out is replaced by a line that says so, and a model with an image limit gets that many. The runner also tells a harness what the turn’s model reads, so fast-agent no longer withholds images from the 65 model ids HarnessRouter sends that its own table did not know — most Claude models among them — and a provider’s stated image limit is kept and the call retried within it. Two harness and model pairs are withdrawn outright, fast-agent with Gemini 4 Argon on Google’s own API and Docker Agent with Grok 4.20, after both failed in deck conversations that switched models partway.
What the 0.38 line changes for a self-hosted instance
Section titled “What the 0.38 line changes for a self-hosted instance”Three things in the v0.38 line change what a self-hoster has to do, and they are the release’s own instructions rather than this guide’s:
- Rotate your MCP tokens if an agent you do not fully trust has run on the instance.
v0.38.0keeps a remote MCP server’s address and credentials in the server and gives the session a local address holding one token that stops working when the turn ends, but older sessions, checkpoints and their git history keep the copies they already hold. - Keep
/data/secret-keywith the volume. An install with noHR_SECRET_KEYnow gets one at its first start, kept in/data/secret-key(root’s, mode 600), and records stored in plain text are encrypted at that start. That protects a copy of the secret store, not a copy of the whole volume, because the key sits beside the data; to keep them apart, setHR_SECRET_KEYto the value in that file and delete the file, and do not set a new value over a generated key — it cannot open what is already stored. A token left on a harness moves the first time that harness is read. - Check what you mounted. Through
v0.38.0a session’s reads and writes kept root’s supplementary group, so an agent could use a link to reach what group root can reach. On the default image that reaches very little, but a volume you mount can hold more: if it holds files group root can read or write, and an untrusted agent has run there, treat what they hold as exposed, and rotate any credential among them.
Environments
Section titled “Environments”HarnessRouter is the reference implementation for UHP 2026-09-28 Environments. Task override behavior follows metadata.environment per PR #331, schema, conformance and gateway implementation.
The current Tasks prose table still carries one stale top-level environment row; that documentation drift is not treated as a second implemented wire form.
Primary sources
Section titled “Primary sources”- HarnessRouter v0.29.1
- PR #381 — relay streaming and upstream liveness
- HarnessRouter v0.29.0
- PR #373 — Kilo CLI, MiniMax Code, Grok Build and Agent Zero
- HarnessRouter v0.28.7
- PR #369 — GPT-6.1 Sol
- PR #368 — public artifact isolation and revocation
- PR #343 — Microsoft 365 Runtime Plugin
- HarnessRouter v0.26.18
- PR #350 — Claude Sonnet 5.5 and Runtime Plugin availability
- PR #351 — Claude Sonnet 5.5 matrix
- PR #266 — Runtime Plugins
- PR #264 — CheetahClaws
- PR #321 — Environments
- PR #331 — metadata.environment
- Current protocol source