The unified Agent Harness interface is here—but don't rush to take apart your backend just yet

Anyone building agent products will eventually run into a very concrete problem: switch to another harness, and you have to rewrite the backend again.

Let's clarify the concepts first. A model API only handles input and output; what actually completes a task is the harness. It wraps around the model and is responsible for calling tools, managing files, running commands, handling permissions and retries, and deciding when a task is finished. Codex, Claude Code, Gemini CLI, and Hermes all fall into this category. They may use similar models, but their behavior is different.

Akshay calls this phase Harness Engineering 2.0. There have already been tool protocols, agent communication protocols, and agent interface protocols; now it's the harness's turn. Developers have released UHP, the Unified Harness Protocol, aiming to define a unified task interface layer for harnesses. HarnessRouter is its open-source server implementation.

The video below illustrates the difference very clearly: on the left is direct integration, where the product backend is wired to Codex, Claude, and Gemini separately, and sandboxing, streaming, and output formats all have to be handled individually. On the right is HarnessRouter, a central layer that manages sandboxing, files, recovery, sessions, and tracking, with clients like Codex, Claude Code, and Gemini CLI connecting to the same backend.

UHP works in a straightforward way. The product backend sends a task containing a harness_id. HarnessRouter reads this ID and starts the selected harness in an isolated session. The harness continues running its own native agent loop and streams progress back. Files, artifacts, failure information, and final output all come back through the same interface.

Without UHP, every harness integration requires separately handling task execution, sessions, streaming events, file uploads and downloads, cancellation paths, error classification, and output formats. Integrating Claude Code versus Codex looks like swapping a CLI, but in practice you're maintaining another execution stack.

UHP codifies this layer as an HTTP contract. It borrows the shape of the OpenAI Responses API and uses POST /v1/responses to create tasks. A response records one task, and a session strings together responses that share conversation state and a working directory. A configured harness consists of a base harness plus model, instructions, skills, tools, MCP servers, and limits. Real-time tasks use SSE; each event carries a type and sequence number, and clients process text output, tool activity, files, and task status in order. Large files are uploaded, and generated files become artifacts. Follow-up tasks use previous_response_id to continue the same session.

There's an easy point to misunderstand here. What UHP standardizes is the task lifecycle, not making different harnesses behave consistently. As Akshay clearly writes in the article, different runtimes may still choose different plans, tools, files, and models. You also cannot directly continue the original session across harnesses. If you want Claude Code to take over a task started by Codex, you need to open a new session and pass over a work summary, next-step instructions, and relevant files. It's like handing a task to another developer: the work can continue, but they aren't running with your in-head context.

The real-world benefit is on the integration side. Harnesses such as Codex, Claude Code, Gemini CLI, Hermes, and Pi can plug into the same product backend while retaining their own tools, skills, models, and agent loop. Developers can switch harnesses without redoing product integration, the same task can run across harnesses, and adding a new harness no longer means piling on another execution stack. HarnessRouter currently supports 30 harness bases, and the Console shows 11 built-in harnesses, including Codex, Claude Code, and Hermes.

The cost data is also worth looking at. According to the official benchmark, changing only the harness while keeping the model fixed reduced costs by 25% to 64% on several healthcare compliance tasks. When changing both harness and model, the difference between the highest- and lowest-cost configurations was 99.8%. These numbers can't be directly applied to every workload, but they are enough to show that harness choice itself affects cost. The official release also includes Harness Arena, where developers can run their own tasks under different configurations.

For local deployment, HarnessRouter is self-hosted. The Docker image contains three services: Console is the browser UI, Gateway handles the UHP API and harness configuration, and Runner starts harness processes in the session workspace. Data, installed harness CLIs, provider integrations, session files, and workspaces are stored in the /data volume. Only the Console port is exposed; Gateway and Runner listen on loopback inside the container. Community Edition requires Docker, about 4GB of disk space, and an API key for a supported model provider. The default username and password are both harnessrouter.

The security boundaries need to be clear. Sessions are isolated using separate OS users and workspaces, but they do not run in separate containers. Provider credentials should not be placed in environments readable by agent tools. Application API keys should not go into browser code. Deploying outside loopback requires TLS and the controls in the UHP security specification. The current UHP version is 2026-09-12, and the project has published a written specification, an OpenAPI 3.1 schema, JSON Schemas, and runnable conformance checks.

Alibaba Cloud Qoder has already adopted UHP, using the HarnessRouter API as its agent backend. This signal is more interesting than repository star counts, because it shows that a unified harness interface is beginning to enter real product pipelines.

A commenter in the replies worried that unifying all harnesses behind one interface sounds beautiful, but the trouble really begins the first time auth and sessions don't line up. That concern is not unwarranted. UHP can reduce duplicated integrations, but it cannot make all runtimes suddenly speak the same dialect. The value of HarnessRouter is that it brings task submission, progress, files, cancellation, and result viewing into one contract, so teams can first get multi-harness workflows running locally and then decide which choices to expose to users in the product.

The repository is Apache 2.0: http://github.com/HarnessRouter/harnessrouter

Akshay's original article: https://x.com/i/article/2100874380012056576