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.
- Source repo
- HarnessRouter/harnessrouter
- Stars
- ★ 3.6k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A product team wants to embed coding agents like Codex or Claude Code into its product without writing a separate backend integration per harness.
- Not a fit if
- Teams unwilling to run and maintain their own Docker host, keys, and backups
- Users who want a managed service with no self-hosted infrastructure
- Source review
- 67/100 · Some gaps
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.
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}'.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| HarnessRouter Community Edition This agent | 67 · Some gaps | Self-hosted serviceFree + model costs | ★ 3.6k | today | Python | Codex · Claude Code |
| Qwen Gate | Insufficient evidence | CLIFree | ★ 203 | 2mo ago | TypeScript | OpenAI API |
| My Free Code | 54 · Major gaps | Self-hosted serviceFree + model costs | ★ 625 | 5d ago | Python | Claude Code · OpenAI API · Claude API |
| OtoDock | 77 · Good | Self-hosted serviceFreemium | ★ 193 | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.37.0-rc.15 Pre-release
Release notes excerpt
Full Changelog: https://github.com/HarnessRouter/harnessrouter/compare/v0.37.0-rc.14...v0.37.0-rc.15View on GitHub ↗
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.