# AI use cases for Harnessrouter (HarnessRouter/harnessrouter)

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Use cases: 6 | Page: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/

HarnessRouter Community Edition is a self-hosted, Apache-2.0 service that gives one API for running agent harnesses such as Codex and Claude Code.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Run agent tasks from your product backend through one API: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/run-agent-tasks-from-product-backend/
- Retry agent tasks without running them twice: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/retry-agent-tasks-without-duplicate-runs/
- Compare harnesses on cost and latency for one task: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/compare-harnesses-on-cost-and-latency/
- Build a custom harness tuned to your product workflow: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/build-custom-harness-for-product-workflow/
- Pass secrets to agents through env, not prompts: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/pass-secrets-to-agents-through-env/
- Generate dashboard SQL from a read-only database schema: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/generate-dashboard-sql-from-database-schema/

## How to run agent tasks from your product backend through one API with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README

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

**Who it is for:** A developer building an AI product who needs agent tasks run by Codex or Claude Code without managing harness setup.

**The problem:** Each agent harness has its own setup, sessions and failure handling, which slows down adding agent features to a product.

**The outcome:** Your backend sends a task with a harness ID, gets a response from the agent, and the task appears in the Console workspace.

### Steps

1. Run `docker run -d --name harnessrouter -p 127.0.0.1:3000:3000 -v harnessrouter:/data harnessrouter/harnessrouter` (inferred, check the README)
2. Run `docker logs -f harnessrouter` and wait for the line `[harnessrouter] ready on :3000`
3. Open http://localhost:3000, sign in, change the default password in Profile, then add a provider key under Bring Your Own Key
4. Create an API key under API Keys in the Console and store it as HARNESSROUTER_API_KEY in your backend
5. Send a POST to /v1/responses with metadata.harness_id set to codex and a model served by your provider

### Prompt to paste into your agent

```text
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.
```

### Caveat

The default URL only works when your backend and the CE instance run on the same computer, so other machines or containers need a reachable URL.

Risk, credentials: The HARNESSROUTER_API_KEY must stay on your backend and never be exposed in browser code.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/run-agent-tasks-from-product-backend/

## How to retry agent tasks without running them twice with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

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

**Who it is for:** A backend developer whose network calls to agent tasks sometimes time out and get retried.

**The problem:** A retried request can start the same agent task again, which wastes model spend and can repeat side effects.

**The outcome:** Both requests return the same response id, and the session contains one turn.

### Steps

1. Complete the first use case so the API key and base URL are set
2. Run `IDEMPOTENCY_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())')` to create one key for the logical request
3. Send the same POST to /v1/responses twice with the header Idempotency-Key set to that value
4. Compare the two returned id values
5. Use a new key for each new logical request and do not reuse a key with a different body

### Prompt to paste into your agent

```text
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.
```

### Caveat

Changing only the stream value still counts as the same request, so a retry that changes stream will return the first result.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/retry-agent-tasks-without-duplicate-runs/

## How to compare harnesses on cost and latency for one task with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Intermediate | Time: 60 minutes | Basis: From the README

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

**Who it is for:** A product lead choosing a harness and model for a feature and needing cost and speed data.

**The problem:** The lowest-cost and fastest harness setup changes by task, so guessing wastes money or adds latency.

**The outcome:** You get a side-by-side view of how each harness and model pair handled the same task.

### Steps

1. Complete setup and connect at least one provider under Bring Your Own Key
2. Open Agent harnesses in the Console and choose a supported harness
3. Select New task, pick a model, and give every configuration the same task text
4. Review the live progress and the files each run produces
5. Read the methodology at https://harnessrouter.ai/benchmarks before drawing conclusions

### Prompt to paste into your agent

```text
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.
```

### Caveat

The README says the fastest and lowest-cost configurations vary by task, so one run does not show which setup is best for other tasks.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/compare-harnesses-on-cost-and-latency/

## How to build a custom harness tuned to your product workflow with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Intermediate | Time: 45 minutes | Basis: From the README

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

**Who it is for:** A product developer who needs an agent to behave a specific way for a recurring workflow in their app.

**The problem:** A built-in harness does not know your product rules, so each task needs the same instructions repeated.

**The outcome:** A reusable custom harness that you call by its harness ID for your product tasks.

### Steps

1. Open Agent harnesses and select New harness
2. In Add harness, set the Name, Base harness, and Default model, then select Create and configure
3. In Harness Settings, add Agent instructions, configure Tools (optionally Add MCP), and add Skills
4. Select Save Changes
5. Select Run Task to test the saved configuration

### Prompt to paste into your agent

```text
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.
```

### Caveat

The base harness cannot be changed after creation, so pick it carefully before you save.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/build-custom-harness-for-product-workflow/

## How to pass secrets to agents through env, not prompts with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Advanced | Time: 60 minutes | Basis: From the README

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

**Who it is for:** A developer whose agent needs a deploy or API token and who wants to keep it out of prompts and logs.

**The problem:** Pasting a long token into a prompt risks the model retyping it wrong and leaking it in stored records.

**The outcome:** The agent reads the value from an environment variable, and the stored record and trace redact it.

### Steps

1. Store the secret in your workspace through PUT /v1/mcp-secrets/{ref}
2. Set the harness env map so a variable points to vault:<name>
3. Write the task so it refers to the variable, for example 'the token is in $DEPLOY_TOKEN'
4. Run the task and check the response, stream and trace for the value
5. Give the token a short lifetime and least privilege for the user and task

### Prompt to paste into your agent

```text
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.
```

### Caveat

The README says the redaction protects the record, not the agent, so the token must still be scoped tightly.

Risk, credentials: Redaction protects the stored record, but an agent that can read a secret can still send it elsewhere if a prompt or page tells it to.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/pass-secrets-to-agents-through-env/

## How to generate dashboard SQL from a read-only database schema with Harnessrouter

Repo: [HarnessRouter/harnessrouter](https://github.com/HarnessRouter/harnessrouter) | Difficulty: Advanced | Time: 90 minutes | Basis: From the README

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

**Who it is for:** A data analyst who wants dashboard charts built from a database without writing each SQL query by hand.

**The problem:** Writing dashboard queries for every chart takes time, and the schema has to be read first.

**The outcome:** A harness reads your schema and writes SQL that powers dashboard charts.

### Steps

1. Complete setup and open Starter Kits in the Console
2. Set HR_SECRET_KEY to encrypt stored database connections
3. Connect a reachable database using a read-only account
4. Review the sample-row setting before you connect
5. Select a harness and model supported by your connected providers and run the Dashboards kit

### Prompt to paste into your agent

```text
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.
```

### Caveat

The README says Starter Kits use different licensing terms, so review those terms before using the kit commercially.

Risk, credentials: The database connection stores credentials, so use a read-only account and set HR_SECRET_KEY first.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/harnessrouter-harnessrouter/generate-dashboard-sql-from-database-schema/