How to use Harnessrouter: what you can do with it

6 use cases

• Run agent tasks from your product backend through one API

  Call a self-hosted, OpenAI Responses-compatible API to run harness tasks from your own backend.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Intermediate
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, start a local Community Edition instance and send a POST to <base-url>/v1/responses with metadata.harness_id set to codex and the input 'Reply with exactly: it works.'. Expected output: a response whose text is 'it works.' and a matching task in the Console. Verify the HTTP status is 200 before reporting success.

  Share Email me this

• Retry agent tasks without running them twice

  Reuse one Idempotency-Key so a retried request returns the first result instead of a new execution.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Intermediate
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, send the same POST to <base-url>/v1/responses twice with one Idempotency-Key header. Expected output: both responses have the same id and the session has one turn. Verify that a second request with the same key but a different body returns 409 before reporting success.

  Share Email me this

• Compare harnesses on cost and latency for one task

  Run the same task on several harness and model pairs and pick the cheapest or fastest one.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Intermediate
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, run the same task <task-description> on two harness and model pairs in the Console. Expected output: a short table of which pair was faster and which produced the cheaper run. Verify that both runs used the same task text before reporting the comparison.

  Share Email me this

• Build a custom harness tuned to your product workflow

  Create a harness with its own instructions, tools, MCP server and skills, then test it before use.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Intermediate
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, create a custom harness named <harness-name> on a supported base harness and add agent instructions for <workflow>. Expected output: a saved harness that completes a test task. Verify that the test run finishes before reporting the harness as ready.

  Share Email me this

• Pass secrets to agents through env, not prompts

  Give an agent a token through the harness env map so it never appears in the prompt text.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Advanced
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, store a secret <secret-name> with PUT /v1/mcp-secrets/{ref} and run a task that reads it from an env variable. Expected output: the task completes and the secret value does not appear in the response or trace. Verify the value is absent from the stored record before reporting success.

  Share Email me this

• Generate dashboard SQL from a read-only database schema

  Use the Dashboards starter kit to have a harness write chart queries from your schema.

  • REPO HarnessRouter/harnessrouter
  • Software and DevOps
  • Advanced
  View prompt

  Using the HarnessRouter repo at https://github.com/HarnessRouter/harnessrouter, connect a read-only database <db-connection> in the Dashboards starter kit and ask the harness to write queries for <chart-list>. Expected output: SQL queries that run against the schema. Verify each query runs on the read-only account before reporting them as ready.

  Share Email me this

Quick start with Harnessrouter

1. Check you have what it needs: Docker installed; About 4 GB of free disk space; A provider API key for at least one supported model provider.
2. Open HarnessRouter/harnessrouter on GitHub and read the README and license.
3. Run docker run -d --name harnessrouter -p 127.0.0.1:3000:3000 -v harnessrouter:/data harnessrouter/harnessrouter (inferred, check the README)
4. Run docker logs -f harnessrouter and wait for the line [harnessrouter] ready on :3000
5. Open http://localhost:3000, sign in, change the default password in Profile, then add a provider key under Bring Your Own Key
6. Create an API key under API Keys in the Console and store it as HARNESSROUTER_API_KEY in your backend

These steps come from our top use case, Run agent tasks from your product backend through one API, which also has a copy-paste agent prompt.

Using the Deduped MCP, get the setup steps for HarnessRouter/harnessrouter

claude mcp add --transport http deduped https://dedupedai.com/mcp

Harnessrouter alternatives · Best AI repos for Software and DevOps

About this repo

• Who it is forDevelopers building an AI product who want agent tasks run by existing harnesses behind one self-hosted API.
• Why it is hot3.3k stars, launched 76 days ago
• LanguagePython
• Sourcegithub.com/HarnessRouter/harnessrouter · Back to Hot repos

Requirements

• Docker installed
• About 4 GB of free disk space
• A provider API key for at least one supported model provider
• Python 3 if you use the Idempotency-Key example

Related repos

• Trended earlier REPO aafqaq/codex-lb-enhanced Codex LB Enhanced Codex LB Enhanced is a self-hosted gateway that pools several upstream accounts behind Codex-compatible and OpenAI-compatible endpoints, with failover, session recovery, quota headers, and diagnostics.
• Trended earlier REPO Ai-Eastern/reuse-before-build Reuse Before Build reuse-before-build is an Agent Skill that makes coding agents search existing code, tests, and libraries before writing new ones, then decide to Take, Borrow, or Build.
• Trended earlier REPO aibuildai-inc/aibuildai-llm-posttrain-agent Aibuildai LLM Posttrain Agent A source-code release of a recursive self-improving agent that designs, runs, and iterates on post-training experiments for LLMs.