HarnessRouter/harnessrouter

What it claims

HarnessRouter Community Edition is a single Docker container that runs agent harness CLIs (Codex, Claude Code, and others such as Hermes) as backends behind an OpenAI Responses-compatible endpoint. You pick the harness per request with metadata.harness_id. It is self-hosted with your own provider keys, needs no HarnessRouter account, and ships no bundled model or trial key. The code, the UHP schemas and the conformance suite are Apache 2.0.

How it works

The container holds three processes, and only the Console port is published:

flowchart TD
  P[Your backend / browser] -->|port 3000| C[Console]
  subgraph Container
    C -->|same-origin proxy| G[Gateway :8080<br/>Responses API, lifecycle]
    G -->|loopback| R[Runner :8081]
    R --> W[Per-session workspace<br/>as separate OS user]
    V[/data volume: db, files,<br/>secrets, workspaces/]
  end
  R -->|model calls| M[Your configured provider]

• Isolation: sessions get separate workspaces and operating-system users, not separate containers. Agents get a native filesystem, shell and Git.
• Ports: the Gateway (:8080) and Runner (:8081) listen only on loopback inside the container. The Console (:3000) is the entry point for both the UI and the API.
• Harness CLIs: these are installed on first launch and kept on the /data volume.

How to use it

You need Docker, about 4 GB of disk and a provider API key.

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

1. Wait until docker logs -f harnessrouter shows [harnessrouter] ready on :3000.
2. Sign in to the Console and change the default password.
3. Add a provider key under Bring Your Own Key.
4. Create an API key under API Keys. It is shown once.

Call the API like this:

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

Other API details:

• Streaming: "stream": true returns server-sent events.
• Spec: the OpenAPI spec is at /v1/openapi.json, with a browsable copy at /v1/docs.
• Files: upload with POST /v1/files, then reference the file in an input_file block. It is placed in the agent's working directory before every turn that carries it.
• Secrets: a harness env map accepts $headers.X-Name (the header must be declared in additional_headers), vault:name (stored via PUT /v1/mcp-secrets/{ref}), or literal values. Values that arrive through a reference are redacted from the response, stream, trace and stored record.
• Custom harnesses: set agent instructions, tools, MCP servers and skills. The base harness cannot be changed after creation.

Limits

• Redaction protects the record, not the agent. An agent that can read a token can also exfiltrate it if a prompt or page tells it to. The page advises using short-lived, task-scoped, least-privilege tokens.
• No exact strings in prompts. Do not put long exact values (tokens, IDs, hashes) in the prompt, because models drop and swap characters. Pass them as files or env vars.
• Root is required. Do not run the container with --user, because the entrypoint and Runner need root to manage per-session users. Session isolation relies on OS users, not containers.
• Keep it on loopback at first. Keep the 127.0.0.1 binding until the default credentials are changed. Public exposure requires the separate TLS guide.
• Upgrades are manual. docker pull does not upgrade a running container; follow the upgrade and backup guide.
• Licensing:
• Harness CLIs remain under their upstream licences.
• Starter Kits use different terms from Community Edition.
• Cloud upload copies harness configuration only, not keys, sessions or files.
• Benchmark has no numbers. The page mentions a comparison of eight harness × model configurations but gives no figures in the text.