🔀 既存のエージェントハーネスをResponses形式の1つのAPIで束ねる自己ホスト基盤HarnessRouterの構造と使い方

HarnessRouter Community Edition（以下 CE）は、Claude Code や Codex などの既存エージェントハーネスを、製品のバックエンドとして 1 つの HTTP API から呼び出す自己ホスト型の実行レイヤです。
この記事では、CE の構造、データ、Docker での構築、API の使い方、運用の勘所を、2026-09-23 時点の main ブランチとリリース v0.23.7 に基づいて整理します。

この記事の全体像。以下、順に解説します。

HarnessRouterとは

HarnessRouter CE は、既存のエージェントハーネスを製品のバックエンドとして使うための自己ホスト型実行レイヤです。
ライセンスは Apache-2.0 です。
リポジトリには Unified Harness Protocol（UHP）の参照実装、機械可読スキーマ、適合性スイートが同梱されています。

UHP は、アプリケーションとハーネスのあいだを 1 つの HTTP 契約でつなぐ公開仕様です。
protocol/README.md は現行版を 2026-09-12、ステータスを Draft standard と宣言しています。
仕様上のハーネスは、計画し、ツールを呼び、ファイルを編集し、結果を返す一式のエージェントランタイムです。

UHP 2026-09-12 は、タスク面を OpenAI Responses API に揃える方針です。
CE はそのサーバ実装です。
製品は自前のインスタンスへタスクを送り、ハーネスの選択、セッションの継続、進捗、ファイル、キャンセル、失敗の記録を同じ API で扱えます。
モデルへの推論リクエストは、利用者が接続したプロバイダへ向かいます。
鍵、セッション、ファイル、ワークスペースは利用者のボリュームに残ります。

HarnessRouter Cloud（https://harnessrouter.ai/ ）は、同じ UHP 契約をホスト側が運用する別サービスです。
Cloud のサイトは、サーバレスの隔離サンドボックス、保守、スケールを提供内容として説明しています。
CE の Quickstart が挙げる前提は、Docker、約 4 GB のディスク、プロバイダ API キーの 3 点です。

リポジトリの基本情報です。
Stars と forks は 2026-09-23 08:51 JST 時点の値で、日々変わります。

近い選択肢との違いを、各公式が述べている実行の単位で比べます。

向く場面は次のとおりです。

特徴

• 製品からの利用単位はタスクです。仕事を渡し、ハーネス自身のツールとセッションで進め、結果とファイルを返します。
• アプリケーション側で扱えるのは、タスクの開始、セッションの継続、進捗のストリーム、ファイルの入出力、タスクのキャンセル、構造化エラーと実行トレースの 6 項目です。
• ハーネスの指定は metadata.harness_id、継続は previous_response_id、進捗は Server-Sent Events です。
• UHP の拡張は metadata、少数の追加フィールド、追加のオブジェクト型に置かれます。ワイヤの形が Responses に揃っているため、既存の Responses クライアントからもタスクを送れます。
• ただし完全互換ではありません。tools と include は予約フィールドとして受理だけされ、無視されます。ツールは呼び出し側ではなく、ハーネス側の設定として持たせます。
• カスタムハーネスとして、名前、ベース、既定モデル、エージェント指示、ツール、スキルを保存して再利用できます。ツールには MCP サーバを加えられます。
• プロバイダ鍵はコンソールから Bring Your Own Key として接続します。製品連携用の API キーは同じインスタンスの API Keys で発行し、表示は一度だけです。
• 配備は Docker コンテナ 1 つです。公開される入口はコンソールだけです。名前付きボリュームが、データベース、ファイル、導入済みハーネス CLI、ワークスペースを保持します。
• セッションごとに別のワークスペースを持ち、ネイティブなファイルシステム、シェル、Git のワークフローを使えます。
• 初回起動時に、有効なハーネス CLI がボリュームへ入ります。各 CLI のライセンスは上流のままです。
• CE のコンソールでは、製品アナリティクスのパイプラインが停止しています。

接続できるハーネスは、プロバイダ種別ごとに self-hosting guide が次のように列挙しています。

検証と計測の公開資料も付いています。

• docs/support-matrix.md は、first turn、follow-up、model switch、artifact、recycle の 5 シナリオを、プロバイダ節ごとの表で記録しています。2026-09-23 時点で 40 節あり、各節末の件数を足すと pairs 1421、passed 6918、scenario runs 6974 です。全体の総計文はファイルにありません。
• 公開ベンチマーク（Care Prep）は、同一タスクと同一入力に対する 8 つのハーネス×モデル構成を比べています。コストは 0.47〜223 credits、レイテンシは 1 分 25 秒〜4 分 36 秒です。同ページは、この幅の大部分がモデル階層の差で、同一モデルでのハーネス差はコスト 1.5〜2.1 倍、レイテンシ最大 1.95 倍と説明しています。
• README の Starter Kits は Slides、Sheets、Dashboards、Videos の 4 種です。ライセンスは CE とは別条件です。
• ローカルで保存したカスタムハーネスは、設定として Cloud の宛先へアップロードできます。

構造

CE の実行時構造を、C4 のシステムコンテキスト、コンテナ、コンポーネントの順に示します。
待受の境界が明確なので、ネットワーク図も加えます。
CE は 1 つのコンテナで動きます。
Cloud は、同じ UHP をサーバレスの隔離サンドボックスで提供する別の実行境界です。
ゲートウェイの探索文書は default_version に 2026-09-12、適合クラスに full を返し、versions には 2026-08-11 も並びます。

システムコンテキスト図

プロトコル上の役割は Client、Server、Harness の 3 つです。
CE と Cloud はどちらも Server の実装で、クライアントが Server へ送る契約は UHP だけです。
図のエージェントハーネスには、Codex、Claude Code、Hermes、DeepSeek Harness、Gemini CLI、Pi、OpenCode、Qwen、Cline、Oh My Pi、goose、Kimi、Aider、OpenHands、System One が入ります。

コンテナ図

コミュニティ版コンテナ

• コンソールとゲートウェイはユーザー agent で動きます。
• ランナーは root で動き、エージェントプロセスをセッションごとの uid に切り替えます。
• 既定の資格情報の渡し方は HR_SANDBOX_TRUST=owner です。ゲートウェイが解決したプロバイダ鍵を、ランナー経由でハーネスへ渡します。
• メディア生成の鍵解決は、ゲートウェイ内の media_plane が行います。
• 保存の既定は HR_BACKING=local です。COSMOS_ENDPOINT が空のとき、制御状態は control_sqlite に置かれます。

コンテナ外

Cloud へのアップロードが写すのはハーネス設定だけです。
プロバイダ鍵、セッション、生成ファイルはローカルのボリュームに残ります。

コンポーネント図

コンソール

コンソールの実体は Next.js 15 と React 19 のスタンドアロンサーバです。
ホスト版と同じコードベースで、版フラグが CE の表示面を選びます。
CE で案内される面は、キット、ハーネス、タスク、API キー、統合です。
ホスト版のアカウントサービス向けの /api/engine は、CE では 501 を返します。

ゲートウェイ

app.py は /v1/llm で、サンドボックス向けの資格情報ブローカも持ちます。
owner モードの CE では、ハーネスがプロバイダへ直接通信します。
ランナーへの指示は、ループバックの /turn、/hydrate、/checkpoint、/produced、/file です。

ランナー

server.py の BACKENDS は、各ハーネスのイベントを Claude Code の stream-json 形式へ揃えます。
レジストリ名は claude、codex、hermes、pi、dsh、opencode、qwen、gemini、cline、omp、goose、kimi、aider、openhands、systemone の 15 個です。
Hermes だけは専用のビルダーを持たず、_run_hermes_bg が state.db をポーリングして Claude 形式のイベントを合成します。
セッションディレクトリはそのセッションの uid が所有し、ワークスペースの親はセッションから一覧も書き込みもできないモードです。

ネットワーク図

• Dockerfile の HEALTHCHECK は 127.0.0.1:8080/healthz を見ます。
• README の docker run は、ホスト側を 127.0.0.1:3000 にバインドします。
• プロダクト向けの公開基点は http://localhost:3000/api/harness です。ゲートウェイ直下の /v1 はその先にあります。

データ

対象は UHP 2026-09-12 のオブジェクトと、CE のゲートウェイがそれを置く保存領域です。
属性名は OpenAPI と仕様本文のワイヤ名です。
保存側の列名は gateway/backing.py、gateway/control_sqlite.py、gateway/control_store.py の定義です。

概念モデル

所有関係を subgraph で、利用関係を矢印で表します。

情報モデル

属性を 4 つの図に分けて示します。
型名は string、int、bool、float、list、map です。
図中の objectKind はワイヤの object、itemType はワイヤの type、defaultModel はワイヤの default を表します。

探索文書とモデル一覧です。

ハーネスとプラグインです。

セッション、応答、ファイルです。

保存領域です。

主なオブジェクトの必須フィールド

Response の metadata で仕様が名前を持つキーは、session_id、requested_model、model_fallback、model_fallback_reason、ignored_fields です。
リクエスト側の metadata.harness_id がハーネスの選択です。
tools と include は予約フィールドで、送ると ignored_fields にその名前が入ります。
2026-09-12 で増えたエラーコードは、plugin_not_found、plugin_conflict、plugin_invalid、unsupported_plugin_schema、unsupported_transport です。

識別子の形

保存の実体

3 つの設定、Dockerfile の HR_DATA_DIR=/data、docker-compose.yml のマウント、entrypoint の DATA_DIR、がすべて /data を指します。

• 両 SQLite は WAL モードです。entrypoint は *.db を owner agent・mode 600 に、blobs と secrets を mode 700 にします。
• グラフのラベルは Harness、HarnessSession、HarnessResponse、HarnessApiKey、Workspace です。OWNS 辺は acct.{org} からセッションへ、USES 辺はセッションからハーネスへ張られます。
• 応答の正本は blob の responses/{id}.json です。グラフの HarnessResponse は索引です。

control.body の kind ごとの役割です。

ソースが固定している主な blob の key です。

構築方法

前提

• 必要なものは Docker、約 4 GB のディスク、モデルプロバイダの API キーです。
• イメージ名は harnessrouter/harnessrouter で、初回の取得サイズは約 700 MB です。
• 1 コンテナの中に Console、Gateway、Runner が入り、公開するのは Console だけです。
• コンテナは uid 0 で起動します。Console と Gateway はユーザー agent で、Runner はセッション uid の切替のため root のまま動きます。
• データベース接続と Cloud 宛先キーの暗号化には HR_SECRET_KEY を使います。ダッシュボード接続を置く前にこのパスフレーズを決めておきます。

┌─ HarnessRouter container ─────────────────────────────────┐
│  Console :3000   ← only published port                    │
│       │ same-origin proxy                                 │
│       ▼                                                   │
│  Gateway :8080   Responses API + harness lifecycle        │
│       │ loopback                                          │
│       ▼                                                   │
│  Runner  :8081   runs harnesses in session workspaces     │
│                                                           │
│  /data volume   database · files · secrets · workspaces   │
└───────────────────────────────────────────────────────────┘

Docker での起動

README の最短手順は、名前付きボリューム harnessrouter を /data に付けて起動する形です。

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

初回はログを追い、準備完了の行を待ちます。

docker logs -f harnessrouter

[harnessrouter] ready on :3000

• 別のホストポートを使うときは左側だけを変えます（例: -p 127.0.0.1:3100:3000）。
• ログの backends available: が、そのボリュームで導入済みのバックエンドです。
• 導入するバックエンドは HR_BACKENDS で選びます。既定は claude,codex,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider,openhands,systemone の 15 個です。
• ソースからビルドするときにブラウザ層を入れるには、ビルド引数 WITH_BROWSER=1 を使います。

Compose を使う場合、リポジトリの docker-compose.yml は ports が "3000:3000" です。
self-hosting guide の手順は次の順です。

1. ports を 127.0.0.1:3000:3000 に書き換える
2. cp .env.example .env で .env を作る
3. docker compose up -d で起動する

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:latest
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

認証の初期値

• Console の初期ユーザー名とパスワードは、どちらも harnessrouter です。
• サインイン URL は http://localhost:3000、セッション Cookie の名前は hr_selfhost です。
• 起動時に初期値を差し替える変数は HR_AUTH_USER と HR_AUTH_PASSWORD です。
• Profile で保存した資格情報は /data/selfhost-auth.json に入り、保存後は環境変数より優先されます。
• 製品バックエンドの資格情報は、Console の API Keys（http://localhost:3000/keys）で作る sk-hr- で始まるキーです。Authorization: Bearer で送ります。

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER=you \
  -e HR_AUTH_PASSWORD=the-password-you-chose \
  harnessrouter/harnessrouter

ローカルでの確認には、Cookie でログインしてからカタログを取得する方法も使えます。

curl --fail-with-body -sS -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"<your-password>"}'

curl --fail-with-body -sS -b hr.cookies http://localhost:3000/api/harness/v1/models

BFF は、有効な Cookie のときだけ内部ヘッダ x-harness-internal を付けてゲートウェイへ転送します。
Bearer だけのリクエストでは Authorization をそのまま渡し、成否はゲートウェイの API キー解決が決めます。

プロバイダ接続

• Console の Bring Your Own Key で Add Integration を押し、名前、プロバイダ、API キーを入力します。
• このキーはモデル呼び出し用で、Console パスワードとも sk-hr- キーとも別物です。
• カスタムエンドポイントは、API 形式、URL、キー、モデル行を持ちます。モデル行は、ハーネスが選ぶ id と、エンドポイントが受け取る名前の組です。
• Console の一括設定 API は PUT /api/harness/v1/admin/integrations です。GET はキーを伏せて返します。

スクリプトで配備するときは環境変数を使います。
接続の秘密名は harness-conn-{name}、バックエンドのポリシー名は harness-policy-{backend} です。

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'
-e HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE='{"chain":["anthropic"]}'

OpenAI 互換のエンドポイントは、provider を openai にして base_url を加えます。

-e HR_SECRET_GLOBAL_HARNESS_CONN_LOCAL='{"name":"local","provider":"openai","api_key":"…","base_url":"https://api.example.com/v1"}'
-e HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX='{"chain":["local"]}'

プロバイダもポリシーも空のまま Codex にタスクを送ると、ゲートウェイは HTTP 400 で次のエラーを返します。

{"error":{"type":"invalid_request_error","code":"invalid_input","message":"no provider configured for backend 'codex'. Add an integration for a provider that serves 'gpt-5.4-mini', or configure a connection policy"}}

設定するキー

ゲートウェイが読む主な環境変数です。
テナントの既定は global です。

環境変数名は、FileSecretStore._env_key が次の規則で組み立てます。
環境変数の値は、ディスク上の秘密より優先されます。

def _env_key(tenant: str, name: str) -> str:
    return "HR_SECRET_" + re.sub(r"[^A-Za-z0-9]", "_", f"{tenant}_{name}").upper()

カスタムハーネス

• 組み込みハーネスは、この手順なしでも使えます。
• Agent harnesses の New harness で、Name、Base harness、Default model を指定し、Create and configure を押します。
• Harness Settings で Agent instructions、Tools、必要なら Add MCP、Skills を足します。
• Save Changes のあと Run Task で設定を試します。
• 既定モデルは作成後に変更できますが、base は作成時の値のままです。
• API で作るときは POST /api/harness/v1/harnesses です。読み取りの id は chrn_ で始まります。
• 組み込みハーネスは、metadata.harness_id に codex のようなベース名を渡して指定します。

利用方法

呼び出しのベース URL は、バックエンドから見た CE の URL です。
同一マシンの既定は次のとおりです。

export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness

OpenAPI は $HARNESSROUTER_BASE_URL/v1/openapi.json から取得できます。
以降の説明では UHP の論理パス（/v1/...）を使います。
CE では、すべてのパスの前に /api/harness を付けます。

必須パラメータ

tasks.md で必須とされているのは input だけです。
README の例は、これに model、metadata.harness_id、stream を添えています。

• previous_response_id と harness_id が別のハーネスを指すと、409 と harness_mismatch です。
• 要求モデルをそのハーネスが提供していないときは、422 と model_unavailable、または既定モデルへの置換です。置換時は metadata.requested_model と metadata.model_fallback が付きます。
• Idempotency-Key ヘッダは初回では任意ですが、POST /v1/responses を再送するときは同じ鍵が必須です。

ターンの実行

Console では Agent harnesses からハーネスを選び、New task でモデルを選んで指示を送ります。
API では POST /v1/responses を呼びます。
モデル id は、接続したプロバイダが提供するものに合わせます。

curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
  -H 'content-type: application/json' \
  -d '{
    "input":"Reply with exactly: it works.",
    "metadata":{"harness_id":"codex"},
    "model":"gpt-5.4-mini",
    "stream":false
  }'

カスタムハーネスを使うときは、chrn_ で始まる id を渡します。

{
  "input": "Summarise README.md in three bullets.",
  "model": "claude-sonnet-4.6",
  "metadata": { "harness_id": "chrn_08dae611630d467ab3e67ed792570ae5" },
  "stream": true
}

• self-hosting guide の成功例では、status: completed、message 内の output_text、metadata.session_id が返ります。ただし仕様上、何も生成しなかったタスクの output は空になり得ます。
• 同じタスクの再読取は GET /v1/responses/{response_id}、入力の再取得は GET /v1/responses/{response_id}/input_items です。
• カタログは GET /v1/harnesses と GET /v1/models です。
• モデルの available: true は、その時点で資格情報があり、そのハーネスにそのモデルを提供できることを意味します。

セッションの継続

次のタスクのボディに、直前の応答の id を previous_response_id として置きます。
サーバは同じ作業ディレクトリ、同じハーネス、同じ metadata.session_id で実行します。
model はターンごとに変えられます。

{
  "input": "Now add tests for the function you just wrote.",
  "previous_response_id": "resp_a1b2c3"
}

• 未知の応答 id は 404 と response_not_found です。
• セッションの一覧は GET /v1/sessions です。クエリは limit、cursor、harness で、最終ページの next_cursor は null です。
• 1 件の取得は GET /v1/sessions/{session_id}、履歴は GET /v1/sessions/{session_id}/turns です。
• 共有は POST・GET・DELETE /v1/sessions/{session_id}/share です。共有ビューは読み取り専用です。

ファイルと成果物

小さなファイルは、input 配列の input_file に data URL で埋め込みます。

{
  "input": [
    { "role": "user", "content": [
        { "type": "input_text", "text": "Summarise this." },
        { "type": "input_file", "filename": "q3.pdf",
          "file_data": "data:application/pdf;base64,…" }
    ]}
  ]
}

大きなファイルは POST /v1/files（multipart/form-data）で先にアップロードし、file_id で参照します。

{ "type": "input_file", "file_id": "file_abc123" }

• 画像は input_image です。
• 上限を超えたアップロードは 413 と file_too_large です。
• 成果物は、アシスタントメッセージの annotations に container_file_citation として載ります。CE の container_id はセッション id、成果物の file_id は cfile_ で始まります。
• セッションのファイル一覧は GET /v1/sessions/{session_id}/files、一括取得は GET /v1/sessions/{session_id}/files/archive です。
• バイト列の取得は GET /v1/containers/{container_id}/files/{file_id}/content です。PDF プレビューは末尾の /content を /pdf に置き換えた GET /v1/containers/{container_id}/files/{file_id}/pdf です。
• README は、長いトークンをプロンプト本文に書かず、ファイルとして渡すよう勧めています。

ストリームとキャンセル

"stream": true の POST /v1/responses は text/event-stream を返します。

data: {"type":"response.created","sequence_number":0,"response":{…}}

data: {"type":"response.output_text.delta","sequence_number":7,"item_id":"msg_1","output_index":0,"content_index":0,"delta":"Sum"}

data: {"type":"response.completed","sequence_number":42,"response":{…}}

• 先頭は response.created、終端は response.completed、response.incomplete、response.failed のいずれか 1 件です。
• テキストの断片は response.output_text.delta です。
• 切断してもタスクはサーバ側で続きます。GET /v1/responses/{response_id} で追えます。ハーネス単位のライブ供給は GET /v1/harnesses/{harness_id}/events です。
• タスク単位の停止は POST /v1/responses/{response_id}/cancel、セッション内の実行中作業の停止は POST /v1/sessions/{session_id}/cancel です。
• キャンセルしたタスクの終端イベントは response.failed で、応答の status は cancelled です。それまでの出力とセッションは残ります。
• "stream": false の結果は、同じ入力のストリームが組み立てる output と同じです。

運用

起動確認

• docker run は約 1 秒で戻ります。ブラウザを開くのは、ログに ready 行が出てからです。
• 初回は有効なハーネス CLI をボリュームへ入れるため時間がかかります。2 回目以降はキャッシュ分だけ速くなります。
• ready 行の直後に接続が拒否されるときは、Console サーバの起動を数秒待ちます。
• Aider と OpenHands は各約 700 MB あり、新しいボリュームでは 1〜2 分かかります。
• Ctrl+C はログの追跡を終えるだけで、コンテナは動き続けます。

ログ

• backends available: が、その起動で実際に入ったバックエンドの一覧です。失敗した名前は requested but not installed の警告に残り、他のバックエンドは動き続けます。
• 既定パスワードのままでは、起動のたびに次の警告が出ます。

[harnessrouter] WARNING: using the DEFAULT password. Set HR_AUTH_PASSWORD, or change it from the profile page, before exposing this instance.

• Profile でパスワードを保存したあとは、資格情報の出所が起動ログに出ます。

[harnessrouter] sign in as 'harnessrouter' (credentials set from the profile page)

• 0.8.2 以降、root 以外での起動は拒否され、その旨がログに 1 行出ます。

ボリューム

• 名前付きボリューム harnessrouter を /data にマウントします。データベース、ファイル、導入済み CLI、ワークスペースが再起動後も残ります。
• セッション作業ディレクトリの既定は /data/workspaces です。
• アイドル状態の作業ディレクトリは、既定 72 時間（HR_WORKSPACE_TTL_HOURS）で削除されます。削除後のセッションはチェックポイントから再構成されます。0 にすると作業ディレクトリを残します。
• エージェントはセッションごとの OS ユーザーで動きます。別セッションのファイルや秘密ストアは、所有者の違いで読み取りが拒否されます。
• ボリュームを削除すると永続データも消えます。docker compose down -v はボリュームも消します。

再起動とイメージ更新

docker start harnessrouter
docker restart harnessrouter

docker pull はイメージを取得するだけで、動いているコンテナは旧イメージのままです。
更新の手順は、バックアップ、pull、古いコンテナの stop と rm、同じボリューム・ポート・設定での作り直し、の順です。

docker pull harnessrouter/harnessrouter
docker stop harnessrouter
docker rm harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

• HR_AUTH_PASSWORD、HR_SECRET_KEY、HR_BACKENDS を付けていた場合は、作り直し時にも同じ値を渡します。
• Compose では docker compose pull のあと docker compose up -d です。
• latest は現行リリースを追います。特定リリースはバージョンタグ、同一バイトはイメージダイジェストで固定します。
• Profile でパスワードを保存すると Console が短時間再起動します。実行中のターンは継続し、他のブラウザはサインアウトします。

バックアップ

• コピーの前にコンテナを止めます。停止中の SQLite とファイルが一貫したバックアップになります。
• ボリュームのパーミッションを保ち、HR_SECRET_KEY をデプロイ記録と一緒に保管します。
• 復元は、ボリュームと設定を戻してから代替インスタンスを起動します。
• HR_SECRET_KEY が保存時と違うと、データベース接続と Cloud 宛先キーの復号に失敗します。

サポートマトリクスの読み方

• シナリオは 5 個です。first turn、同一セッションの follow-up、途中の model switch、artifact、recycle です。
• 判定語は pass、FAIL（理由は Notes）、n/a（not run）の 3 つです。
• 40 のプロバイダ節の節末件数を足すと pairs 1421、passed 6918、scenario runs 6974 です。同じハーネスとモデルが複数のプロバイダ節に出る点に注意します。
• 表の Harness 列に出る名前は 11 個です。claude-code、cline、codex、dsh、gemini、goose、hermes、omp、opencode、pi、qwen です。
• docs/support-matrix-notes.md の Totals（695 pairs over eight columns）は、2026-09-06 の v0.13.5〜v0.13.13 での別時点の記録です。
• 合格は、完了に加えて docs/harness-verification.md の 4 規則で判定されます。接続の一致、頼んだ model id、ファイルカードと保存ファイルの一致、Responses 専用モデルを chat/completions 専用ハーネスのカタログから外すこと、です。

再現コマンドは scripts/support-matrix/README.md にあり、Playwright と Chromium が必要です。

export BASE=https://your-instance HR_USER=harnessrouter HR_PASS=... PROVIDER=tokenrouter
HARNESSES=claude-code,codex,opencode,pi RESULTS=results-A.json LOG=log-A.txt node run.mjs
HARNESSES=hermes,dsh,qwen,cline       RESULTS=results-B.json LOG=log-B.txt node run.mjs
HR_API_KEY=... python3 fill-connection.py results-A.json results-B.json
python3 render.py <(jq -s add results-A.json results-B.json) > ../../docs/support-matrix.md

認証情報のローテーション

• Console パスワードは Profile で変更します。保存時は現在のパスワードも求められます。
• パスワードを失ったときは、/data/selfhost-auth.json を削除して再起動します。資格情報は HR_AUTH_USER と HR_AUTH_PASSWORD の値に戻ります。

docker exec harnessrouter rm /data/selfhost-auth.json
docker restart harnessrouter

• API キーは Console の API Keys で作ります。秘密は作成時に一度だけ表示されます。ワークスペース単位で、同じページでローテーションと失効ができます。
• プロバイダキーは Integrations で管理します。PUT は文書全体を置き、name が一致する行を差し替えます。
• タスクに渡す秘密は、ファイルかハーネスの env で渡します。vault:name 参照は PUT /v1/mcp-secrets/{ref} で自分のワークスペースに入れた秘密だけを読み、応答やトレースからは伏せられます。
• README は、エージェントが読める値はプロンプトやページの指示で外へ送られうると注意しています。渡すトークンは短寿命・最小権限にします。
• 脆弱性の報告は、GitHub Security タブの Report a vulnerability か contact@harnessrouter.ai です。

公開 URL とストリーム

• 既定の publish は 127.0.0.1:3000:3000 で、ホストのループバックからだけ届きます。
• 外部に公開するときは、ループバックの前に TLS 終端プロキシを置きます。ガイドの Caddy の例では、flush_interval -1 でイベントストリームを即時に流します。

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1
    }
}

• サインインゲートが入ったのは 0.3.0 です。0.1.x と 0.2.0 は、ポートに届いた相手がそのまま入れます。
• 別マシンや別コンテナからの API ベース URL は、呼び出し側から届く CE の URL にします。呼び出し側の localhost は呼び出し側自身を指します。
• ストリームの期限は無通信タイムアウトで判定します。サーバは 30 秒ごとに : keep-alive コメントを出すべき、と仕様は定めています。
• 非ストリームのクライアント期限は、タスクの timeout_seconds に余裕を足した値以上にします。

バックエンドの選択と同時実行

• HR_BACKENDS を絞ると、初回の容量と時間を減らせます（例: HR_BACKENDS=opencode）。
• Console はゲートウェイのカタログにある base をすべて表示します。インストールに失敗した base へのタスクは最初のターンで失敗し、失敗名はコンテナログに出ます。
• ターンは global と tenant の 2 つのセマフォを取ります。値は HARNESS_GLOBAL_CONCURRENCY と HARNESS_TENANT_CONCURRENCY で、未設定時のローカル既定は max(2, os.cpu_count() or 2) です。実効値は 2 つの小さい方です。
• PUT /v1/harnesses/{id} は可変設定の全体を置き換え、省略したフィールドはクリアされます。読み取りのキャメルケースを、書き込みのスネークケースに戻してから送ります。
• Cloud にアップロードできるのはカスタムハーネスです。組み込みハーネスは、先にカスタムハーネスを作ってからアップロードします。

ベストプラクティス

鍵の持ち方

• Console パスワード、プロバイダ API キー、HarnessRouter API キーを、それぞれ別の保管場所に置きます。
• API キーは製品バックエンドの秘密ストアに置き、ブラウザのコードや Git には置きません。
• 長いトークン、ID、ハッシュはプロンプト本文に書かず、ファイル添付か env の参照で渡します。モデルが文字を落とすことがあるためです。
• ダッシュボード接続と Cloud 宛先を保存する前に HR_SECRET_KEY を固定し、更新と再起動のたびに同じ値を渡します。
• ダッシュボード用の DB アカウントには SELECT 権限だけを与えます。文パーサに加えた第二の防御になります。

バインドアドレス

• 初期資格情報のあいだは 127.0.0.1 への publish を維持します。
• 公開するときは、パスワード変更のあとに TLS 終端プロキシの背後へ置きます。
• プロキシでは flush_interval -1 相当の設定で、イベントをバッファさせないようにします。
• イメージは 0.3.0 以降のバージョンに固定します。
• --user と Compose の user: は付けません。0.8.2 以降は root 以外の起動を拒否します。

ボリューム

• 名前付きボリュームを /data に付けたまま運用します。-v を省くと、データベースと CLI と作業ディレクトリがコンテナの寿命に閉じ込められます。
• バックアップと更新の前にコンテナを止めます。
• 更新手順では docker compose down -v を使いません。
• ディスクを優先するなら作業ディレクトリの TTL は既定の 72 時間のまま、作業ディレクトリを残すなら HR_WORKSPACE_TTL_HOURS=0 にします。
• 検証ノートには、プロバイダあたり 170 セッションで 62 GB のディスクを使った記録があります。大量に回す場合は終わったセッションを削除します。

ハーネス選択

• タスクに使うハーネスとモデルの組は、先に Console で 1 回通して実行経路を確認します。
• モデルは、接続したプロバイダが実際に提供する id を選びます。
• Responses API 専用のモデルは、chat/completions 専用のハーネスでは使えません。
• Codex の gpt-5.3-codex は、同じタスクで別モデルを使ったあとにツールが拒否される例がサポートマトリクスに記録されています。このモデルは新しいタスクで始めます。
• カスタムエンドポイントでは、行ごとの provider_id でエンドポイントに送るモデル名を指定します。拒否される組み込みツールは接続の disabled_tools に書きます。
• 定常運用の接続追加は、環境変数ポリシーより Integrations 画面を使います。表の外の組み合わせが空ターンになるのを避けられます。
• systemone は型付き行動空間の決定ループで、ワークスペース上の CLI とは別種です。

検証

• ハーネス対応を変更したら、1 ターンの応答ではなく 5 シナリオとカスタムハーネスで確認します。CONTRIBUTING.md は出荷前に docs/harness-verification.md を読むよう指定しています。
• 検証の 1 列はプロバイダ 1 つにし、他の integration を削除して隔離します。
• 別インスタンスの合格リストは引き継ぎません。経路とキーがインスタンスごとに違うためです。
• SpreadsheetBench Verified の先頭 50 タスク（deepseek-v4.1-flash、ウェブツール無効）では、resolved が pi 40/47、opencode 39/48、dsh 36/46、cline 36/47 です。トークンは fresh input、cached input、output に分けて扱います。
• 適合スイートの日付付き結果として、2026-09-04 に protocol 2026-08-11 で 64 チェック全通過、2026-09-15 に CE 0.17.2 で full の 74/74 通過の記録があります。

注意点

ドキュメントと実装の乖離

資料間の食い違い

未確認事項と未解決の Issue

トラブルシューティング

エラーコードは protocol/versions/2026-09-12/errors.md の定義です。
HTTP 200 の status: "failed" はタスクの失敗で、非 2xx のエラー封筒はリクエストの失敗です。

まとめ

HarnessRouter CE は、Claude Code や Codex をはじめとする既存のエージェントハーネスを、OpenAI Responses の形に揃えた UHP という 1 つの API の裏に並べる自己ホスト基盤です。
Console、Gateway、Runner を 1 つのコンテナに収め、鍵、セッション、成果物を利用者のボリュームに残したまま、ハーネスやモデルを切り替えられます。
導入は docker run 1 行で始められます。
製品で使う際は、ループバックバインド、パスワード変更、HR_SECRET_KEY の固定、Idempotency-Key 付きの再送、の 4 点を最初に押さえると安全です。
サポートマトリクスとベンチマークは計測条件と時点が資料ごとに異なるため、採用判断には自分のプロバイダとタスクで 5 シナリオを通して確かめることをおすすめします。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• HarnessRouter/harnessrouter
• README
• protocol/README.md
• UHP architecture 2026-09-12
• UHP tasks
• UHP sessions
• UHP files
• UHP harnesses
• UHP plugins
• UHP errors
• UHP schema
• OpenAPI 2026-09-12
• Unified Harness Protocol
• HarnessRouter Cloud
• Care Prep benchmark
• self-hosting guide
• .env.example
• docker-compose.yml
• Dockerfile
• entrypoint.sh
• support matrix
• support matrix notes
• harness verification
• SpreadsheetBench column
• conformance report 2026-09-15
• Release v0.23.7
• Docker Hub
• SECURITY.md
• Issue 201
• Issue 202
• Issue 207