HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
A harness runs only for its own organization and workspace (#408)
github-actions[bot]f509767af7b6
diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.mdindex 7fa9635a..a40b2546 100644--- a/docs/self-hosting-guide.md+++ b/docs/self-hosting-guide.md@@ -988,6 +988,9 @@ variables. It is a setup check, not a technical prerequisite for the API.3. Copy the secret shown once. Store it in your product backend's secret store or environment. The examples call this variable `HARNESSROUTER_API_KEY`.The key is scoped to the selected workspace and can be rotated or revoked on the same page.+A harness runs with a key of its own workspace: a task that names a harness of another workspace,+or of another organization, is answered `404 harness_not_found`, the same as an id that does not+exist. A built-in base (`codex`, `claude-code`, ...) runs with any key.It is created in this self-hosted instance and authenticates requests to that CE deployment. It isneither a Cloud key, your Console password, nor the model-provider key configuredin **Integrations**. Never put it in browser-side code or commit it to Git.diff --git a/docs/support-matrix-notes.md b/docs/support-matrix-notes.mdindex f2485f00..a0b6464d 100644--- a/docs/support-matrix-notes.md+++ b/docs/support-matrix-notes.md@@ -3038,3 +3038,33 @@ as before). A test asks the question at the instant the ready record is writtenorder. On the candidate: an environment with a pip, an npm and an apt package built in 9 s, a turnstarted in the same instant its record read ready completed using the environment's package, and theenvironments column passed on pi, Codex and Claude Code, 9 of 9 tasks.++## Who may run a harness (2026-10-06, 0.31.2)++Until this release the harness id alone was what ran a harness: a comment in the code called it+"the run capability", written for a marketplace in which callers run a harness and its owner pays.+Anyone who knew an id (console links carry it) could start a task on the harness, with the owner's+connected plugs and database, on the owner's connections. Richard's rule, made on the hosted service+first and the same here: "a harness can run by id and workspace's API key".++The caller's organization must be the harness's; a caller narrowed to a workspace runs that+workspace's harnesses, a harness from before workspaces counting as the Default Workspace's; a key+for the whole organization runs any of its harnesses; a built-in base has no owner. The refusal is+`404 harness_not_found`, what every other route answers for a harness that is not the caller's. It+is the same test the harness list already applied, so what a key lists, it runs, and a harness made+with a key is stamped with that key's workspace, so what a key makes, it runs.++Candidate `0.31.2-rc.1` in a side container on the test VM, on a copy of an instance with 77 harnesses (36 stamped with the Default Workspace, 41 from before workspaces). Keys were minted for two workspaces and for the whole organization, and a harness was made with workspace one's key:++| Caller | Result |+|---|---|+| Workspace one's key, its own harness | completed |+| Workspace two's key, that harness | `404 harness_not_found`, and the harness is not in its list |+| A key for the whole organization | completed |+| Workspace two's key, a built-in base | completed |+| Another organization (the gateway's internal door, another organization named) | `404 harness_not_found`, also when it names the right workspace |+| The console in workspace one | completed |+| The console in workspace two, and in the Default Workspace | `404 harness_not_found` |+| The Default Workspace's key, a harness made before workspaces | completed |++Through the console itself (Playwright): a harness created and run on pi, with its skill, script and tool policy. Claude Code tasks complete, and all plugin checks pass on Claude Code, Codex and pi, each of which makes its own harness and runs it.diff --git a/gateway/app.py b/gateway/app.pyindex 78080b32..ad24191f 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -3083,6 +3083,26 @@ async def _drain_inflight() -> None:pass+def _turn_harness_owned(principal: dict, hv: dict | None) -> None:+ """A harness runs only for the organization that owns it, and for a caller narrowed to a+ workspace (a workspace's key, the console's workspace) only when it is that workspace's+ harness. Richard, 2026-10-06: "a harness can run by id and workspace's API key". Until then the+ harness id alone was the run capability: anyone who knew it (console links carry it) ran the+ harness with the owner's connected plugs and database, on the owner's connections. The rule was+ made on the hosted service first, where no product relied on the old one, and is the same here.+ A key for the whole organization runs any of its harnesses; a harness from before workspaces+ belongs to the Default Workspace. Answered as not found, as every other route does for a harness+ that is not the caller's, so the id reveals nothing."""+ if not hv:+ return # a base id: no record, no owner+ if str(hv.get("org") or "") != str(principal.get("org") or ""):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")+ ws = str(principal.get("workspace") or "")+ default = bool(principal.get("workspace_default")) or ws.endswith("__hr_default")+ if ws and not _workspace_keep(str(hv.get("workspace") or ""), ws, default):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")++def _turn_harness_check(harness_id: str, hv: dict | None) -> None:"""A turn addressed to a harness runs on THAT harness or not at all. A deleted one answers thesame 404 as the read endpoints. An id that names no harness at all used to run as a turn with@@ -8438,11 +8458,10 @@ async def create_response(body: CreateResponseBody, request: Request):raise uhp_error(403, "forbidden", "This credential starts runs on the one harness it drives.","metadata.harness_id", {"harness_id": _cal.get("inner")})hv = await _harness_vertex(harness_id) if harness_id else None- # A deleted harness cannot run new turns (same 404 as the read endpoints). Cross-org runs are- # ALLOWED — sibling products legitimately run a user's harness under a platform credential, and- # the marketplace model is exactly "callers run it, the owner pays infra". Until entitlements- # land, the unguessable harness id is the run capability.+ # A deleted harness cannot run new turns (same 404 as the read endpoints), and a harness runs+ # only for the organization and workspace that own it: see _turn_harness_owned._turn_harness_check(harness_id, hv)+ _turn_harness_owned(principal, hv)# The project layer this task reads: the request's, else the harness's. Resolved and checked# here, before anything is allocated, so a missing or unbuilt environment is a 4xx and not a# failed turn.diff --git a/gateway/tests/test_harness_run_owner.py b/gateway/tests/test_harness_run_owner.pynew file mode 100644index 00000000..ed200f13--- /dev/null+++ b/gateway/tests/test_harness_run_owner.py@@ -0,0 +1,65 @@+"""A harness runs only for the organization and workspace that own it (Richard, 2026-10-06).++Until then the harness id was the run capability: a caller that knew it ran the harness with the+owner's connected plugs, on the owner's connections. Made on the hosted service first; the same+rule and the same tests here.+"""+import sys+from pathlib import Path++import pytest++sys.path.insert(0, str(Path(__file__).resolve().parents[1]))+import app as gw # noqa: E402+from fastapi import HTTPException # noqa: E402++HV = {"org": "org.owner", "workspace": "space.team"}+++def _refused(principal, hv=HV):+ with pytest.raises(HTTPException) as e:+ gw._turn_harness_owned(principal, hv)+ return e.value.status_code+++def test_another_organization_is_told_there_is_no_such_harness():+ assert _refused({"org": "org.other"}) == 404+ assert _refused({"org": ""}) == 404+++def test_the_owner_runs_it_from_its_own_workspace_or_with_an_organization_wide_key():+ gw._turn_harness_owned({"org": "org.owner", "workspace": "space.team"}, HV)+ gw._turn_harness_owned({"org": "org.owner", "workspace": ""}, HV) # a key for the whole organization+++def test_a_key_of_another_workspace_of_the_same_organization_does_not_run_it():+ assert _refused({"org": "org.owner", "workspace": "space.elsewhere"}) == 404+++def test_a_harness_from_before_workspaces_belongs_to_the_default_workspace():+ legacy = {"org": "org.owner", "workspace": ""}+ gw._turn_harness_owned({"org": "org.owner", "workspace": "org.owner__hr_default"}, legacy)+ gw._turn_harness_owned({"org": "org.owner", "workspace": "space.x", "workspace_default": True}, legacy)+ assert _refused({"org": "org.owner", "workspace": "space.team"}, legacy) == 404+++def test_a_base_with_no_record_has_no_owner():+ gw._turn_harness_owned({"org": "org.anyone"}, None)+++def test_a_credential_that_drives_one_harness_runs_it_in_its_own_organization():+ # the scoped credential of a calibrating run names an organization and no workspace+ gw._turn_harness_owned({"org": "org.owner", "member": "calibrator:s1", "calibration": {"inner": "chrn_1"}}, HV)+ assert _refused({"org": "org.other", "member": "calibrator:s1", "calibration": {"inner": "chrn_1"}}) == 404+++def test_the_refusal_is_the_one_a_missing_harness_gets():+ with pytest.raises(HTTPException) as e:+ gw._turn_harness_owned({"org": "org.other"}, HV)+ assert e.value.status_code == 404 and "No harness with that id." in str(e.value.detail)+++def test_every_new_turn_is_checked_right_after_the_harness_is_read():+ src = (Path(__file__).resolve().parents[1] / "app.py").read_text()+ i = src.index(" _turn_harness_check(harness_id, hv)\n _turn_harness_owned(principal, hv)\n")+ assert src.rfind("async def create_response(", 0, i) > src.rfind("\nasync def ", 0, i) - 1