Unified Harness Protocol

Harnesses

Unified Harness Protocol, version 2026-10-19

Before a client can send work it needs to know what can run it, and with which models. This chapter defines discovery, the harness object, and — at conformance class Full — how harnesses are created and changed.

1. Discovering harnesses

GET /v1/harnesses
{
  "harnesses": [
    {
      "id": "chrn_08dae611630d467ab3e67ed792570ae5",
      "object": "harness",
      "name": "Research agent",
      "base": "claude-code",
      "baseLabel": "Claude Code",
      "defaultModel": "claude-sonnet-4.6",
      "systemPrompt": "",
      "mcpServers": [],
      "skills": [],
      "plugins": [],
      "disabledTools": [],
      "maxStep": null,
      "timeoutSeconds": null,
      "createdAt": 1786403298205
    }
  ]
}

A server MUST return only harnesses within the caller's scope. The list MAY be empty — a server with no configured harnesses is valid, and a client MUST handle that rather than assuming index 0 exists.

GET /v1/harnesses/{harness_id}

Returns one harness object, or 404 with code: "harness_not_found".

2. The harness object

Field Type Required Meaning
id string yes chrn_-prefixed
object string yes Always harness
name string yes Human-readable label; not an identifier
base string yes Which harness runtime: codex, claude-code, hermes, …
baseLabel string no Display name for base
defaultModel string no Model used when a task omits model
systemPrompt string no Additional standing instructions
mcpServers array no MCP servers attached to this harness
skills array no Skills available to this harness
plugins array no Installed plugins, each a package of tools and skills; see Plugins
environment string no The environment this harness's tasks read, mounted read-only; requires the environments capability. See Environments
disabledTools string[] no Tools withheld from the agent
maxStep integer | null no Default step budget
timeoutSeconds integer | null no Default wall-clock budget
createdAt integer yes Unix milliseconds

The memories a harness's agent reaches are not a field of this object. The agent is a member and is granted on the memory, like a person; /v1/harnesses/{id}/memories reads what it was granted and keeps two settings (Memories §9).

base values are not enumerated by this specification. A server MAY support bases this document has never heard of, and a client MUST treat base as an opaque string — anything else means the protocol has to be revised every time a harness is released, which is exactly the coupling UHP exists to remove.

3. Models

GET /v1/models
{
  "backends": {
    "claude": {
      "default": "claude-sonnet-4.6",
      "models": [
        { "id": "claude-sonnet-4.6", "label": "claude-sonnet-4.6", "backend": "claude",
          "available": true, "default": true }
      ]
    }
  }
}
GET /v1/harnesses/{harness_id}/models
{
  "harness_id": "chrn_…",
  "backend": "claude",
  "default": "claude-sonnet-4.6",
  "fallback": "claude-sonnet-4.6",
  "models": [ { "id": "claude-opus-5", "available": true, "default": false } ]
}

fallback is deprecated, and is removed no earlier than the second version after this one. It names the model a server would run in place of one it cannot serve, which Tasks §1.3 makes the harness's default, so it only ever repeats default; a server that refuses an unavailable model (model_unavailable) runs none in its place. Servers keep sending it as before. Read default and each model's available instead.

3.1 available is a promise

available: true means the server can serve that model for that harness right now — a credential exists and the provider can reach it. available: false means a request for it will not run as asked.

A server MUST compute available, not assert it. Listing a model as available and then failing the task is the worst outcome for a client: it presents a choice to a user, the user picks it, and the work fails after they have committed to it.

A client SHOULD present unavailable models as disabled rather than hiding them, so a user can see that a model exists and is not configured, rather than wondering why it is missing.

4. Tools and skills

A configured harness carries three things that decide what its agent can do. All three are part of the harness object and are set the same way it is.

4.1 MCP servers

{ "mcpServers": [
    { "name": "vault", "url": "https://mcp.example.com/mcp", "transport": "http", "enabled": true }
] }
Field Required Meaning
name yes Identifies the server to the agent; sanitised to a CLI-safe identifier
url yes Endpoint
transport no http (Streamable HTTP, default) or sse
enabled no Absent or true means enabled
headers no Extra request headers
auth no Bearer token, or a server-side reference the server resolves

This list carries remote servers only, exactly as it did in the previous version. An MCP server that runs as a process (stdio) is declared inside a plugin, which is what gives it a root to run from and a directory to keep state in (Plugins §2.2).

A server MUST connect only the enabled entries for a turn. A disabled entry MUST NOT be contacted at all — not connected and then hidden, which would still leak the turn's existence to whoever operates that endpoint.

An MCP server that cannot be reached MUST NOT fail the task. The turn MUST proceed without those tools, because a third-party endpoint being down is not a reason to lose the user's work. A server SHOULD make the degradation visible in the run rather than silent.

A server MUST NOT advertise MCP support it cannot deliver. If the harness runtime behind it cannot speak the configured transport, that is a broken installation, and reporting it only in a log file inside the workspace is indistinguishable — to the user — from the model refusing to use the tool.

4.2 Skills

A skill is a folder, not a file:

{ "skills": [
    { "name": "vault-manual", "enabled": true, "files": [
        { "path": "SKILL.md",            "content": "---\nname: vault-manual\n---\n…" },
        { "path": "references/codes.md", "content": "…" },
        { "path": "scripts/helper.sh",   "content": "#!/bin/sh\n…" },
        { "path": "assets/logo.png",     "content_b64": "iVBORw0KGgo…" }
    ]}
] }
  • files[].path is relative to the skill's own folder and MUST support nested directories. A server MUST reject a path that escapes the folder.
  • Text is carried in content; binary in content_b64. A server MUST preserve both byte-for-byte.
  • A bundle MUST contain a SKILL.md; a server MUST reject one that does not, at configuration time rather than at run time.
  • A server MUST materialise the whole folder where the agent can read it. Materialising only SKILL.md breaks every skill that carries references, scripts or data — which is most non-trivial skills.
  • enabled: false suppresses a skill, including one inherited from the base.

A server MAY store large bundles out of line, and MUST return the complete file list from:

GET /v1/harnesses/{harness_id}/skills/{skill_id}/files

Round-tripping a harness through GET and PUT MUST NOT lose skill contents. This is the failure worth designing against: an unrelated edit — renaming the harness — silently emptying a skill folder that the user cannot tell is gone until an agent behaves oddly weeks later.

4.3 Disabled tools

{ "disabledTools": ["WebSearch"] }

Names come from the harness base's own tool catalogue. Enforcement differs by runtime and a server MUST NOT overstate it:

  • Where the runtime supports per-tool restriction, the server MUST enforce it as a hard block.
  • Where it does not, the server MUST still convey the restriction to the agent — as a standing instruction — and MUST NOT silently drop it. Dropping it is the worst outcome: the operator believes a tool is off, and it is not.

A client that requires a guaranteed block SHOULD confirm the harness base supports one rather than assuming disabledTools is always hard.

4.4 Plugins

{ "plugins": [ { "name": "contract-review", "enabled": true, "blob": "plg_…" } ] }

A plugin is an Agent Plugins package: plugin.json, mcp.json and skills/, carried as one folder and installed whole. Its servers and skills join the harness's own for every turn; the harness's own mcpServers and skills report only what was written to them and never absorb a plugin's. The object, the composition rule, the export of a harness as a package, and what a hosted server owes a running plugin are in the Plugins chapter. The capability is plugins; a server without it is conformant at every class.

5. Managing harnesses

Conformance class Full only. A client MUST check the harness_management capability first.

5.1 Create

POST /v1/harnesses
{ "name": "Research agent", "base": "claude-code", "default_model": "claude-sonnet-4.6" }

Returns the created harness object. base is REQUIRED and MUST be one the server supports; otherwise 422 with code: "unsupported_base".

A server MUST refuse, rather than store as nothing, what it cannot keep:

  • a field the harness object does not have: 422, naming the field and, when one is close, the field it was probably meant to be;
  • a default_model its base does not run: 422 with code: "model_not_available".

What the harness object comes back with and cannot be written (id, object, createdAt and the server's own read-only fields) MUST be accepted and ignored, so that a harness read and sent back saves. Both refusals hold for an update as well.

A client MAY send Idempotency-Key: <opaque string> on a create. The key belongs to the client and is chosen before its first attempt. It is what makes a retry after a lost answer safe: the client cannot tell whether its first create reached the server, and without a key its retry makes a second harness.

A server that reports the harness_idempotency capability MUST keep a create's key for at least 24 hours, in the caller's scope, and for a repeat of it:

  • answer with the harness the first request created, and not create another;
  • if the first request is still creating that harness, wait for it and answer with it, rather than with a conflict or a not-found;
  • answer 409 with code: "idempotency_key_reused" when the repeat carries a different request.

Once the harness a key created is deleted, the key names no harness, and a repeat creates one as the first request did. A server without the capability ignores the header, so every request creates a harness.

5.2 Update

PUT /v1/harnesses/{harness_id}

Replaces the mutable configuration. A server MUST NOT change id, base, or createdAt. Changing the base of an existing harness would silently change the behaviour of every session already attached to it; a client that wants a different base MUST create a different harness.

Because an update replaces the whole configuration, a client that builds its body from a read overwrites whatever changed between that read and its write: an edit made by a person, or by another client. A server MAY answer a read of a harness (GET /v1/harnesses/{harness_id}) and an update with an ETag header carrying the harness's version, a strong validator that changes whenever something an update replaces changes. A server that answers one MUST honour If-Match on an update of that harness:

  • an If-Match naming the harness's current version, or *, is applied as any update is, and the answer carries the new version;
  • one that names no current version is refused with 412 and code: "precondition_failed", and nothing is written. The client reads the harness again and redoes its change on what it reads;
  • an update without If-Match replaces the configuration as it always has.

The precondition is judged after the caller's scope, so a harness outside it is still 404, and before the body: a body built from a stale read is refused as stale whatever else it would have been refused for. A client that read no ETag MUST NOT assume If-Match is honoured.

5.3 Delete

DELETE /v1/harnesses/{harness_id}

Deleting a harness retires it. What happens to the sessions and responses that used it is the server's to choose, between two rules, and the server MUST say which one it follows:

Sessions are kept (the default). A server that reports the harness_retirement capability false MUST NOT delete the sessions or responses that used the harness. They stay readable and deletable on their own. History that disappears when configuration changes cannot be audited, so this is what a client may assume of a server that says nothing.

Sessions are retired with the harness, under a restore window. A server that reports harness_retirement true MAY remove the harness's sessions and responses with it, and only under these rules:

  • The window is stated when the harness is retired. The delete response MUST carry sessions: "retired" and restorableUntil, the time (Unix seconds) until which a restore is possible. A server's own interface MUST tell the person the length of the window before they confirm, and a client that retires a harness for a person MUST pass restorableUntil on to them.
  • Within the window, a restore brings both back. Restoring the harness (however the server offers it) MUST bring back its sessions and responses with it, as they were. A server MAY withhold them from lists and reads until then; a read of one MAY answer 404.
  • After the window, removal is permanent. The server MAY then remove the harness, its sessions and its responses for good. It MUST NOT remove them earlier, with one exception: a person's own request to erase their data MAY remove the retired sessions that are theirs before the window ends.
  • Never mid-turn. A harness with a task in progress is not retired while it runs. The server either cancels the task first, as POST /v1/sessions/{session_id}/cancel would, and then retires the harness, or refuses the delete with 409 and code: "harness_busy", saying why.

A server MUST NOT remove a harness's sessions or responses when the harness is retired without a window it stated. A server that keeps them MAY say so with sessions: "kept" in the delete response; an absent sessions means kept.

6. Choosing a harness

Non-normative, but the question every client faces:

If the task is… Consider
Code editing in a repository A coding-specialised base (codex, claude-code)
Long-horizon multi-tool work A base with an explicit step budget and strong tool use
Cheap, high-volume classification The smallest model on any base

The point of UHP is that this choice stays reversible. A product that speaks UHP can change base or model with a configuration edit, and can A/B two harnesses against the same input without a second integration.

Unified Harness Protocol 2026-10-19 · Apache-2.0 · defined and maintained in the HarnessRouter open-source repository. The standard can be implemented independently of any hosted service.