Skip to content
UHPUHPDeveloper Guide
Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

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

Source snapshot protocol: 2026-09-28 (as advertised by CE)Release: v0.38.2

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.

CheckpointEvidence to captureIf it fails
Service startsRelease/image identity, readiness log and console accessInspect startup/install errors before changing client requests
Selected backend is usableInstalled executable version, available harness/model and provider routeRepair that backend or credential route; another working backend is not equivalent evidence
Product workflow worksSubmitted Response, terminal state, continuation and retrieved fileKeep 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.

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.

Terminal window
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
docker logs -f harnessrouter

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

CredentialWhat it authorizes
Console loginAdministrative access to the CE instance
Provider API keyModel requests through the selected provider
CE-issued API keyYour 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:

Terminal window
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
}'

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.

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.

CoordinateCurrent state
Stable releasev0.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 commit8e1cf1b598a7ea864fda3a5de064b11289b6ac84
Upstream mainChecked 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 CE2026-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 CEinput_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 package2026.10.19.post5
Executable checks104
Released backends30 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.

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

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.0 keeps 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-key with the volume. An install with no HR_SECRET_KEY now 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, set HR_SECRET_KEY to 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.0 a 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.

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.