HarnessRouter Community Edition
One API to run Codex, Claude Code, Hermes, DeepSeek Harness, and more, self-hosted on your own infrastructure—no harness-specific backends required.
Evidence shows: container starts as root only to create per-session users then drops privileges (README warns against --user), only port 3000 published with Gateway/Runner on loopback, default credentials must be changed with loopback binding kept, secrets live in the /data volume, HR_SECRET_KEY guards stored connections. Deductions: no user-approval gates are documented despite agents running bash/git/filesystem with user credentials (user_confirmation 1); harness CLIs are fetched from upstream at first launch with no manifest, pinning, or SBOM shown, and SECURITY.md explicitly excludes them (dependency_security 1); hence least_privilege and sensitive_data_handling land at 2, not 3. Rollback/recovery (cancellation, resumable sessions, named-volume persistence) is documented but not shown in implementation, scoring 2. License and upstream attribution (full Apache-2.0 text, upstream CLI license notice) are complete, scoring 3.
Evidence shows: docs and tests are internally consistent — the conftest's HR_* variables match the README's HR_AUTH_USER/HR_SECRET_KEY naming, and model-slug mapping has dedicated tests; failure paths are described at contract level (structured errors, CLI exiting 1, hub-cleanup refusing non-rc tags). Deductions: these are static docs and contracts with no concrete error-message specimens; harness CLI availability depends on upstream at runtime, so each criterion stops at 2.
Evidence shows: audience and scenarios are clearly delineated (self-hosters, product developers, starter kits for slides/sheets/dashboards/videos with prerequisites and extra costs noted); capability boundaries are set by SECURITY.md's scope and the 'catalog shown by the running instance' statement. Deductions: trigger precision is largely inapplicable and undocumented (1); environment fit covers only the Docker path — bare-metal and Compose details sit behind links not present in the evidence (2).
Evidence shows: excellent information architecture (README → setup guide → protocol spec/schema/conformance/governance); detailed install notes (port conflict, 4 GB disk, first-launch wait, default-credential table); honest known limitations (no trial key, per-clip video costs, slow first launch, sample-row setting needs review). Deductions: only indirect version hints exist (0.15.7, dates in workflow comments); no CHANGELOG or version-policy file is present, so versioning_changelog scores 1; examples are few and there is no FAQ (2); maintenance responsibility is evidenced by the SECURITY.md SLA and bot workflows but no MAINTAINERS or release cadence (2).
Evidence shows: clear, differentiated marginal value — collapsing N×M harness integrations into one OpenAI Responses-compatible contract (Tasks/Runs/Sessions/Files/Artifacts/Traces); output usability is supported by streaming, artifacts, and structured error contracts. Deductions: the cost-benefit claims ('90%+ savings', '99.8%') are marketing-style citations to an external link unverifiable within the repo, and operational cost is shifted to the configured provider plus first-launch CLI downloads, so cost_benefit scores 2.
Evidence shows: claim traceability has real machinery — the conformance-remeasure workflow replaces the README's recorded-run block with a live measurement and opens no PR on failure, actively preventing figure drift, which is rare; hub-cleanup comments record a concrete 403-scoping debugging history. Deductions: benchmark numbers, the UHP spec, and external sites cannot be corroborated within this repository (cross_source_corroboration 1); the README carries marketing phrasing ('world's first', 'best') though fact/inference separation is otherwise adequate (2).
- Default credentials harnessrouter/harnessrouter must stay behind loopback binding and be changed immediately; exposing an unmodified instance publicly hands over code-execution capability.
- Agent harnesses run bash, git, and filesystem operations with the provider keys you configure; SECURITY.md explicitly says to treat the instance as capable of running code with your credentials — scope keys and network/filesystem access accordingly.
- Harness CLIs are installed online at first launch from upstream; their licenses and security are upstream concerns and this repository does not audit them. Static review could not verify those binaries.
- The container initially runs as root to establish per-session users and then drops privileges; do not break this with --user, but audit the image to confirm the drop actually occurs.
- No CHANGELOG exists in the repository; version information must be inferred from comments and external links. Pin image versions and read the setup guide before upgrading.
- This is a static review (confidence: low); no runs, conformance suite, or benchmarks were executed, and the performance/cost figures in the README were not verified by this assessment.
What does this agent do, and when should you use it?
HarnessRouter Community Edition is the Apache-2.0, self-hosted reference implementation of the first unified interface for agent harnesses. It implements the open Unified Harness Protocol (UHP) and exposes one OpenAI Responses-compatible API for running supported harnesses including Codex, Claude Code, Hermes, PI, and DeepSeek Harness. It ships as a single Docker deployment containing a Console (:3000), a Gateway (:8080), and a Runner (:8081), where the Runner launches one harness CLI process per session. The platform owns the full agent lifecycle contract: tasks and runs, sessions, streaming, files and artifacts, cancellation and recovery, structured errors, and traces. Provider keys, database, files, and workspaces stay on your infrastructure under a /data volume. The repository also includes the UHP specification, OpenAPI/JSON Schema contracts, and a conformance suite. It fits teams that want many harnesses behind one integration without building a backend per harness.
After starting via docker run, the first launch installs the harness CLIs you enable and logs [harnessrouter] ready on :3000. The Console is the single entry point for both UI and API, proxying same-origin to the Gateway, which implements the Responses API and harness lifecycle; the Runner, on a loopback port, runs one agent CLI process per session with its own workspace and conversation state. You add a model provider and its API key under Integrations, then create a task under Agent harnesses—progress streams live into the task, while files, artifacts, errors, and the final result stay attached to its session. You can also call the API directly: POST /api/selfhost/login for a session cookie, then POST to /api/harness/v1/responses with metadata.harness_id (e.g. "codex") and "stream": true for server-sent events. The repo also provides the UHP spec (protocol/versions/), machine-readable schemas (protocol/schema/), and a conformance suite (protocol/conformance/).
- A product team wants to embed coding agents like Codex or Claude Code into its product without writing a separate backend integration per harness.
- An engineering team needs to manage tasks, sessions, streaming, and artifacts for multiple harnesses in one self-hosted environment while keeping keys and data under its own control.
- A developer wants to verify that a harness implementation conforms to the UHP open standard using the conformance suite.
- A team wants to compare cost and latency across harness × model configurations through one API; the README benchmarks show savings above 90% on some tasks.
- A user wants document workflows via harnesses like Hermes, e.g. reviewing an NDA and producing a redline, clean copy, and negotiation memo.
What are this agent's strengths and limitations?
- Single contract: your product integrates once with Task/Run/Session/File/Artifact/Error/Trace semantics; adding or switching harnesses requires no backend redesign.
- OpenAI Responses-compatible API lowers integration friction for clients already familiar with that format.
- Full lifecycle coverage: sessions, SSE streaming, files and artifacts, cancellation and recovery, structured errors, and traces are built in.
- Open, verifiable standard: the UHP spec, OpenAPI/JSON Schema, and a conformance suite are published in the repo.
- Four starter kits (Slides, Sheets, Dashboards, Videos) demonstrate use beyond coding.
- You must supply your own model provider API key; there is no bundled model or trial key, and no task runs until a provider is connected.
- Depends on Docker and roughly 4 GB of disk; harness CLIs are downloaded online on first launch, requiring network access.
- Default credentials (harnessrouter/harnessrouter) mean the instance must stay loopback-bound until the password is changed—exposing it is your responsibility.
- Harness CLIs remain under their respective upstream licenses and run with real filesystem, shell, and Git access, so isolation and security need your own evaluation.
- Cost and latency vary enormously by task and harness × model configuration (README benchmarks: 0.47–223 credits, 1m 25s–4m 36s), so claims require your own benchmarking.
How do you install or deploy this agent?
Requires Docker, about 4 GB of disk space, and an API key from a supported model provider; no HarnessRouter account is needed. Run: docker run -d --name harnessrouter -p 127.0.0.1:3000:3000 -v harnessrouter:/data harnessrouter/harnessrouter. If port 3000 is busy, use -p 127.0.0.1:3100:3000. Keep the loopback binding and do not add --user (the container starts as root to establish per-session users, then runs without root privileges). Version pinning, Docker Compose, and scripted setup are covered in docs/self-hosting-guide.md.
How do you use this agent?
First launch takes longer; run docker logs -f harnessrouter and wait for [harnessrouter] ready on :3000. Open http://localhost:3000 and sign in with initial credentials username harnessrouter, password harnessrouter (or HR_AUTH_USER/HR_AUTH_PASSWORD if configured), then change the password in Profile immediately. Add a model provider and its API key under Integrations—there is no bundled model or trial key, so no task can run until a provider is connected. Under Agent harnesses, choose a harness and create a new task with a model and concrete instructions. API example: curl -s -c hr.cookies http://localhost:3000/api/selfhost/login -H 'content-type: application/' -d '{"username":"harnessrouter","password":"<your-password>"}', then curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses -H 'content-type: application/' -d '{"input":"Reply with exactly: it works.","metadata":{"harness_id":"codex"},"model":"gpt-5.4-mini","stream":false}'.
How does this agent compare with similar options?
The README positions Community Edition versus HarnessRouter Cloud as two implementations of the same UHP contract—self-hosted with full data control versus hosted scale. It also implicitly contrasts with building harness-specific backends, which it eliminates by design.
FAQ
Do I need to pay or create an account?
Is my data safe?
Which harnesses are supported?
How do I call it via API?
/api/selfhost/login for a session cookie, then POST an OpenAI Responses-compatible request to /api/harness/v1/responses with metadata.harness_id to pick a harness and "stream": true for SSE.