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 4 Oct 2026 Source and review policy

Protocol: 2026-09-28Release: v0.29.1

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 4 October: stable is v0.29.1 / d2572192. Upstream main was checked separately at the same d2572192 commit. The release list still contains v0.30.0-rc.3 as a prerelease, 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.

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.

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”
CoordinateCurrent state
Stable releasev0.29.1, published 4 Oct 2026 at 15:17:35 UTC
Stable commitd257219281ef3b5a113fe8d8f2550ae0d12be320
Upstream mainChecked at d2572192, matching stable at this review
UHP protocol2026-09-28 Draft
Conformance package2026.9.28.post3
Executable checks85
Released backends20

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 20:

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 and Agent Zero.

Adapter support does not establish native UHP adoption by the upstream project.

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”