# HarnessRouter

> HarnessRouter is the world's first unified interface for agent harnesses.

Unified interface = 1 + 2 + 3:
1. One Agent API: use one contract for tasks, runs, sessions, streaming, files, artifacts, errors, and traces across every supported harness.
2. Serverless sandboxed execution: run each task on demand in an isolated environment without separately deploying and operating every harness runtime.
3. Tracing for optimization: understand each run and optimize the Harness × Model configuration for each different task.

For its current V1 developer audience, HarnessRouter provides an AI agent API and product backend layer that runs Codex, Claude Code, Hermes, and other supported agent harnesses through these three product layers so a product can return finished, reviewable work.

HarnessRouter operates managed agent harnesses as a service, also called harness as a service (HaaS). It is not a generic LLM gateway, model API wrapper, prompt playground, standalone sandbox provider, or replacement for a product UI. Model routers handle model access; HarnessRouter handles the agent-harness execution lifecycle behind a product.

Best fit:
- Product developers who want to add agent-backed work to an app.
- Developer teams turning a local AI app or Claude Code prototype into a product backend workflow.
- Products that need server-side harness execution, durable sessions, streaming, file intake, artifact return, routing, and a stable UI contract around agent work.

Audience status:
- Developer: current V1 focus.
- Agent authors and automation teams: future V1.5 validation path for deploying and reusing tuned agent configurations.
- Enterprise: future V2 design-partner path for business-task evaluation and governance.
- Labs: future V2 design-partner path for model experiments inside real agent harnesses.

## Primary Resources

- [Agent implementation guide](https://harnessrouter.ai/agents.md): Copy this into Codex, Claude Code, or another coding agent to build a HarnessRouter integration.
- [Markdown integration docs](https://harnessrouter.ai/docs.md): Quick start summary. For implementation, copy /agents.md into the coding agent.
- [Markdown harness catalog](https://harnessrouter.ai/harnesses.md): Supported harness IDs, status, integration notes, and source-backed references.
- [Care Prep Benchmark](https://harnessrouter.ai/benchmarks): Controlled same-task results across eight Codex, Claude Code, and Hermes harness and model configurations, with recorded cost, latency, grounding evidence, and methodology.
- [Human documentation](https://harnessrouter.ai/docs): Human-readable product integration docs.
- [Pricing](https://harnessrouter.ai/pricing.md): Current public pricing summary in Markdown.

## Evidence and Product Surfaces

- [Agent harness rankings](https://harnessrouter.ai/rankings): Attributed usage rankings for reviewed agent harnesses, with source and data-window methodology.
- [Product examples](https://harnessrouter.ai/examples): Runnable and recorded examples of agent-backed product workflows.
- [Blog](https://harnessrouter.ai/blog): Definitions, comparisons, tutorials, announcements, and original analysis about agent harnesses and AI product infrastructure.

## Harness References

- [Codex harness reference](https://harnessrouter.ai/harnesses/codex): Available Coding agent harness. Use harness ID `codex`.
- [Claude Code harness reference](https://harnessrouter.ai/harnesses/claude-code): Available Coding agent harness. Use harness ID `claude-code`.
- [Hermes harness reference](https://harnessrouter.ai/harnesses/hermes): Available Autonomous agent harness. Use harness ID `hermes`.
- [Pi harness reference](https://harnessrouter.ai/harnesses/pi): Coming soon harness reference. Do not target harness ID `pi` in production integrations until public API metadata marks it routable.

## Docs Pages

- [Product vs runtime agent](https://harnessrouter.ai/docs/host-app-vs-runtime-agent): Your product keeps the user experience, auth, data, permissions, and workflow. At runtime, it sends HarnessRouter one authorized end-user task.
- [Workspace](https://harnessrouter.ai/docs/workspace): Workspace API keys, configured agents, sessions, and returned files all live inside the Workspace that serves your product.
- [Configured agent / harness](https://harnessrouter.ai/docs/configured-agent-harness): It combines a base harness, model policy, instructions, tools, skills, and permissions. Your server calls it with the `harness_id` path segment.
- [Session and response](https://harnessrouter.ai/docs/session-and-response): Save the response ID and session ID from the stream. Your product needs both to recover, continue, cancel, and fetch artifacts.
- [Files and artifacts](https://harnessrouter.ai/docs/files-and-artifacts): Fetch generated files from your server, check product ownership, then preview or download them inside your product UI.
- [Authentication](https://harnessrouter.ai/docs/authentication): The browser should never call HarnessRouter directly with the Workspace API key.
- [Base URL](https://harnessrouter.ai/docs/base-url): Build all runtime and management requests against the HarnessRouter API host.
- [Harnesses](https://harnessrouter.ai/docs/harnesses-api): Use harness management endpoints from trusted server code or an authorized admin surface.
- [Models](https://harnessrouter.ai/docs/models): Ask the API for current models and for the models allowed by a configured agent. Treat the choice as part of your product evidence loop.
- [Run a task](https://harnessrouter.ai/docs/run-a-task): Use the configured agent ID as the first path segment. Prefer streaming when users need visible progress.
- [Streaming events](https://harnessrouter.ai/docs/streaming-events): HarnessRouter streams Server-Sent Events in an OpenAI Responses-style wire format with `data:` frames only.
- [Continue a session](https://harnessrouter.ai/docs/continue-a-session): Use continuation for revise, follow-up, incomplete work, or reconnecting to a task context.
- [Upload files](https://harnessrouter.ai/docs/upload-files): Use file upload for documents, data, source bundles, and other user-authorized inputs.
- [Sessions and files](https://harnessrouter.ai/docs/sessions-and-files): Use session endpoints after saving `response.metadata.session_id` from the stream.
- [Cancel a session](https://harnessrouter.ai/docs/cancel-a-session): Closing an SSE connection does not stop the server-side agent. Use cancel when the user intentionally stops work.
- [Errors and idempotency](https://harnessrouter.ai/docs/errors-and-idempotency): Every initial runtime request should include an idempotency key. Reuse it only when retrying the exact same request.
- [Server-side proxy pattern](https://harnessrouter.ai/docs/server-side-proxy-pattern): Your backend validates the product user, maps the feature to a configured agent, calls HarnessRouter, and returns a product-shaped result.
- [Feature key to harness mapping](https://harnessrouter.ai/docs/feature-key-to-harness-mapping): The browser should name the product action. The server should choose the configured agent.
- [Streaming UI](https://harnessrouter.ai/docs/streaming-ui): Your UI should show task progress, save recovery identifiers, and tolerate new stream event types without breaking.
- [File preview and download](https://harnessrouter.ai/docs/file-preview-and-download): Generated artifacts are product data. Your server should authorize every preview and download before relaying bytes.
- [Continue / revise](https://harnessrouter.ai/docs/continue-revise): Continue and revise should feel like one product task evolving, not a new unrelated run.
- [Multi-tenant authorization](https://harnessrouter.ai/docs/multi-tenant-authorization): HarnessRouter returns opaque session and file IDs. Your server decides which product user or tenant may continue, cancel, preview, or download them.
- [Choosing a harness](https://harnessrouter.ai/docs/choosing-a-harness): Run representative tasks through your real product path. Choose from dashboard Trace, stream behavior, recovery, files, artifacts, cost, and quality.
- [Tracing and optimization](https://harnessrouter.ai/docs/tracing-and-optimization): Use the dashboard control plane and your saved product records before changing instructions, model policy, tools, permissions, or runtime limits.
- [Production checklist](https://harnessrouter.ai/docs/production-checklist): Use this as a short release checklist for products that call HarnessRouter.
- [LLM resources](https://harnessrouter.ai/docs/llm-resources): Use these resources when an AI coding agent, search crawler, or documentation tool needs compact HarnessRouter context.

## Guides

- [Claude Code as a Service: Headless, Multi-Tenant, via API](https://harnessrouter.ai/guides/claude-code-as-a-service.md): How to run Claude Code headless behind your product: the API contract, multi-tenant authorization, per-task sandbox isolation, document skills, and configuration comparison.
- [Hermes API: Run the Hermes Agent Behind Your Product](https://harnessrouter.ai/guides/hermes-api.md): How to run Nous Research's Hermes agent through an API: what Hermes is, the task and session contract, model pairing, and what its benchmark results show about cost and speed.
- [What Is an Agent Harness? Definition, Anatomy, Examples](https://harnessrouter.ai/guides/what-is-an-agent-harness.md): An agent harness is the runtime layer around a model that turns it into a working agent: the loop, context, tools, permissions, sandboxing, and recovery. Definition, origins, examples, and how it fits the stack.
- [AI agent API for product features](https://harnessrouter.ai/guides/ai-agent-api.md): What a product needs when users expect completed work: sessions, streaming, files, artifacts, routing, and production controls.
- [Codex API: What Exists, What Doesn't, How to Call It](https://harnessrouter.ai/guides/codex-api-for-apps.md): The current Codex API reality: OpenAI's seven Codex surfaces, what the Codex SDK actually is, why there is no hosted REST API for Codex tasks in current docs, and how to run Codex over HTTP today.
- [Which layer should your product use?](https://harnessrouter.ai/guides/agent-backend-vs-model-router.md): Use this page to separate model access from product-facing agent work with sessions, files, artifacts, and traces.
- [HarnessRouter and OpenRouter](https://harnessrouter.ai/guides/harnessrouter-and-openrouter.md): How model routing and agent-backed product work fit together in one stack.

## Optional

- [Full LLM context](https://harnessrouter.ai/llms-full.txt): Expanded product overview, guides, harness catalog, pricing, and implementation context.
- [Sitemap](https://harnessrouter.ai/sitemap.xml): Complete crawlable URL inventory.

## Guidance

- Use /agents.md when implementing HarnessRouter in a product.
- Use /docs.md for a concise Markdown quick start.
- Use /harnesses.md for supported harness IDs and source-backed harness references.
- Use /benchmarks for the canonical same-task data report and /rankings for attributed usage evidence.
- Use /guides for agent harness definitions, AI agent API architecture, Codex, Claude Code and Hermes integration, and agent backend vs model-router comparisons.
- Do not infer harness capabilities beyond official source links in /harnesses.