정의
HarnessRouter는 여러 에이전트 하네스(Codex, Claude Code, Hermes, PI, DSH, OpenHands 등)를 하나의 통합 API 뒤로 묶어주는 오픈소스 인프라 플랫폼이다. 오픈라우터가 모델들을 API 하나로 묶는 것과 유사하게, 하네스라우터는 하네스(코딩 에이전트 런타임)들을 API 하나로 묶는다는 포지션이다.
핵심 가치 제안:
- 제품 백엔드에 하네스별 개별 통합을 만들지 않고도, 하나의 API로 하네스를 선택·교체할 수 있다.
- 세션, 스트리밍, 파일, 취소, 구조화된 실패 처리를 일관된 인터페이스로 제공한다.
출처: threads-44646b794b312d43617877 (@unclejobs.ai, 2026-09-22) — “하네스 계의 오픈라우터”
아키텍처 개요
하나의 Docker 컨테이너 안에 3계층이 함께 동작한다:
┌─ HarnessRouter container ───────────────────────────────┐
│ Console :3000 ← UI + 공개 API 진입점 │
│ │ same-origin proxy │
│ ▼ │
│ Gateway :8080 Responses API + 하네스 라이프사이클 │
│ │ loopback │
│ ▼ │
│ Runner :8081 세션 워크스페이스에서 하네스 실행 │
│ │
│ /data volume DB · 파일 · 비밀 · 워크스페이스 │
└─────────────────────────────────────────────────────────┘
- Gateway + Runner는 컨테이너 내부 loopback에서만 노출, 외부에는 Console(:3000)만 공개.
- 세션은 별도 컨테이너가 아니라 별도 워크스페이스/OS 사용자로 격리.
- 상태 저장소: SQLite + 파일 (셀프 호스팅 기본), Cloud는 관리형.
지원 하네스 (숫자 지속 증가 중)
2026-09 기준 예시 — Codex, Claude Code, Hermes, PI, DSH, OpenHands 등. 게이트웨이에서 metadata.harness_id로 라우팅한다.
| 하네스 | 비고 |
|---|---|
| Codex (OpenAI Codex CLI) | 에이전트 CLI, 첫 실행 시 컨테이너 내 설치 |
| Claude Code (Anthropic) | 에이전트 CLI, 첫 실행 시 설치 (Anthropic 이용약관 적용) |
| Hermes | Hermes Agent (Nous Research) |
| PI | Pi 코딩 에이전트 |
| DSH | |
| OpenHands | openhands-agent-server 1.49.2 (MIT) 경유, 14번째 베이스로 추가됨 (PR #215) |
| Gemini CLI | 별도 구글 제공자 경유 추가됨 (Path A: API Key, PR #115) |
참고: 에이전트 CLI는 Docker 이미지에 포함되지 않는다 — 라이선스 요건(Anthropic 등 독점 소프트웨어 재배포 방지)이자 크기 최적화로, 첫 실행 시 데이터 볼륨에 운영자 자신의 약관 수용 하에 설치된다. 설치 실패 시 해당 하네스는 “사용 불가”로 처리된다.
UHP (Unified Harness Protocol)
HarnessRouter가 구현하는 공개 버전 관리 규격. Community Edition은 UHP의 Apache 2.0 레퍼런스 구현체 + 스키마 + 적합성 테스트 모음이다.
- 태스크 표면: 의도적으로 OpenAI Responses API와 호환 — 기존 Responses SDK, 스트리밍 파서, UI 컴포넌트를 UHP 서버에서 그대로 사용할 수 있다.
- 정의하는 의미론: 하네스 선택, 영속 세션, 파일, 취소, 하네스 관리 도구·스킬.
- 주요 문서 자원:
- 규격:
protocol/versions/2026-09-12 - OpenAI Responses 호환성 설명:
protocol/README.md - OpenAPI + JSON Schema:
protocol/schema - 적합성 모음:
protocol/conformance— CE 기준 “Full” 배지 - 거버넌스:
protocol/GOVERNANCE.md(명칭 정책, 적합성 게이트, 마크 규칙)
- 규격:
원천: GitHub README, https://unifiedharnessprotocol.org/
배포 / 셀프 호스팅
- 빠른 시작: Docker 1명령
docker run -d --name harnessrouter \ -p 127.0.0.1:3000:3000 \ -v harnessrouter:/data \ harnessrouter/harnessrouter - 요구 사항: Docker, 약 4GB 디스크, 제공자 API 키 (HarnessRouter 계정 불필요, 번들 모델/시험 키 없음)
- 초기 인증:
harnessrouter/harnessrouter(첫 로그인 후 변경 필요) - 제공자 키: Console의 “Bring Your Own Key”에서 추가 — 모델 요청을 승인하는 키이며, API 키·Console 암호와는 별도.
- API 키: Console → API Keys에서 생성, 제품 백엔드에서
HARNESSROUTER_API_KEY로 설정. - 기본 API 호출 예시 (OpenAI Responses 호환):
POST /api/harness/v1/responses Authorization: Bearer $HARNESSROUTER_API_KEY { "input": "Reply with exactly: it works.", "metadata": {"harness_id": "codex"}, "model": "gpt-5.4-mini", "stream": false } - Cloud 경로: 로컬에서 구성한 커스텀 하네스를 Cloud로 업로드 가능 (HR_SECRET_KEY 암호화 필요). 업로드 대상은 하네스 구성만 복사되며 제공자 키·세션·생성 파일은 복사되지 않는다.
배포 변형: 단일 all-in-one 컨테이너(Dockerfile, docker-compose.yml), 공개 URL TLS 배포 가이드 별도.
벤치마크 / 포지셔닝 (공개된 수치)
README에 공개된 요약 벤치마크 (방법론은 harnessrouter.ai/benchmarks):
- 8개 하네스 × 모델 구성 동일 태스크 비교
- 비용: 최저 vs 최고 구성 간 약 99.8% 차이 (223 → 0.47 credits 예시)
- 종단 지연시간: 최대 약 3.2배 차이 (4분 36초 → 1분 25초 예시)
- 주장: “최저 비용/최고 속도 구성은 태스크마다 다르다” — 라우팅을 통한 최적화가 의미 있다는 메시지.
이 수치는 HarnessRouter 측이 자사 사이트에서 공개한 것으로, 독립적 제3자 재현 여부는 별도 확인 필요.
라이선스
- HarnessRouter CE: Apache 2.0 (MIT에서 2026-08-11 변경)
- 에이전트 하네스 CLI: 자체 업스트림 라이선스 적용 (Anthropic Claude Code는 Anthropic 약관, Codex는 Apache 2.0 등) — 컨테이너 이미지에 미포함.
- Starter Kits: 별도 라이선스 (https://github.com/HarnessRouter/starter-kit#licensing)
- NOTICE 파일에 Apache 2.0 고지 및 제3자 고지 수록.
Apache 2.0 변경 사유(프로젝트 설명 기준): 기업이 자체 인프라에서 수정·실행하도록 설계된 프로젝트에서 특허 부여가 실질적 차이 — MIT는 특허에 대해 침묵.
프로젝트 현황 (2026-09-29 GitHub API 기준)
- GitHub: https://github.com/HarnessRouter/harnessrouter
- 스타 2,770 · 포크 284 · 열린 이슈 12 (2026-09-29)
- 최신 릴리스: v0.26.13 (2026-09-29), 총 128개 릴리스 — 하루에도 여러 번 릴리스하는 속도
- 기여자: 18명 — 주요: richard-epsilla (창립자), claude, github-actions 등
- 언어 구성: Python 67.2%, TypeScript 16.9%, CSS 12.1%, JavaScript 1.9%, Shell 1.6%, Dockerfile 0.3%
- 보안 정책: GitHub advisory + contact@harnessrouter.ai
- 커뮤니티: Discord (https://discord.gg/nPcbwqVPb2), LinkedIn, X (@HARNESSROUTER)
- Docker Hub: https://hub.docker.com/r/harnessrouter/harnessrouter
- Star History: https://www.star-history.com/#HarnessRouter/harnessrouter&Date
핵심 아키텍처 (2026-09-13 공개 구조)
하나의 Docker 컨테이너 안에 3계층:
┌─ HarnessRouter container ─────────────────────────────────┐
│ Console :3000 ← UI + 공개 API 진입점 (유일한 공개 포트) │
│ │ same-origin proxy │
│ ▼ │
│ Gateway :8080 OpenAI Responses 호환 API + 하네스 라이프사이클 │
│ │ loopback │
│ ▼ │
│ Runner :8081 세션 워크스페이스에서 하네스 실행 │
│ │
│ /data volume 데이터베이스 · 파일 · 비밀 · 워크스페이스 │
└───────────────────────────────────────────────────────────┘
- Gateway + Runner는 컨테이너 내부 loopback 전용, 외부 노출 없음.
- 세션은 별도 컨테이너가 아니라 별도 워크스페이스 + OS 사용자로 격리.
- 상태 저장: SQLite + 파일 (셀프 호스팅 기본). Cloud는 관리형.
- API: OpenAI Responses API 호환 (
POST /api/harness/v1/responses,metadata.harness_id로 하네스 선택).
최근 주요 개발 (2026-08 ~ 2026-09)
- #234 (2026-09-21): 응답 — 시작되지 않은 턴을 orphan으로 잘못 처리하던 재합성기(reconciler) 수정. 배경 응답은 POST 반환 즉시 읽기 가능, 턴 태스크가 세션 정점(vertex)과 첫 하트비트 기록.
- #232 (2026-09-19): 듀얼 루프 — Calibrator 하네스가 다른 하네스를 구동하고 결과를 넘겨받는 구조. Calibrator는
calibrates필드로 구동 대상 하네스 지정, HR_CALIBRATION_TOKEN으로 플랫폼 API 접근. - #217 (2026-09-19): 규격 스키마가 패키지 안에 동봉되고, 하네스 해상도가 첫 태스크 전에 일어나도록 수정. 누락 스키마/미매칭 harness_id는 ERROR로 조기 종료.
- #215 (2026-09-19): OpenHands V1을 14번째 베이스로 추가 (openhands-agent-server 1.49.2, MIT). 콘솔 매트릭스 247/250, 플러그인 4/4, 적합성 75/75.
- #72 (2026-08): Gemini CLI를 새 에이전트 백엔드로 추가 (구글 API 키 인증, 별도 “google” 제공자).
- #213 (2026-09-18): Console “Integrations” 페이지 → “Bring Your Own Key”로 명칭 변경, Access 아래 배치.
- 2026-08-11: MIT → Apache-2.0 라이선스 변경. 특허 부여 명시, NOTICE 파일 추가.
- 2026-08-09: 올인원 컨테이너 + docker-compose.yml, 라이선스 정정.
지원 하네스 (2026-09 기준, 지속 증가 중)
| 하네스 | 비고 |
|---|---|
| Codex (OpenAI Codex CLI) | 첫 실행 시 컨테이너 내 설치 |
| Claude Code (Anthropic) | 첫 실행 시 설치, Anthropic 이용약관 적용 |
| Hermes | Hermes Agent (Nous Research) |
| PI | Pi 코딩 에이전트 |
| DSH | |
| OpenHands | openhands-agent-server 1.49.2 (MIT), 14번째 베이스 |
| Gemini CLI | 별도 구글 제공자 경유 (Path A: API Key) |
| … | 그 외 계속 추가 중 |
중요: 에이전트 CLI는 Docker 이미지에 포함되지 않음 — 라이선스 요건(Anthropic 등 독점 소프트웨어 재배포 방지)이자 크기 최적화. 첫 실행 시 데이터 볼륨에 운영자 자신의 약관 수용 하에 설치. 설치 실패 시 “사용 불가” 처리.
벤치마크 (공개 수치, 2026-09)
README에 공개된 요약 벤치마크 (방법론: harnessrouter.ai/benchmarks):
- 8개 하네스 × 모델 구성 동일 태스크 비교
- 비용: 최저 vs 최고 구성 간 약 99.8% 차이 (223 → 0.47 credits 예시)
- 종단 지연시간: 최대 약 3.2배 차이 (4분 36초 → 1분 25초 예시)
- 주장: “최저 비용/최고 속도 구성은 태스크마다 다르다” — 하네스·모델 라우팅 최적화의 의미.
이 수치는 HarnessRouter 측 공개값으로, 독립적 제3자 재현 여부는 별도 확인 필요.
Starter Kits (별도 저장소, 별도 라이선스)
- Slides: 브리핑을 슬라이드 콘텐츠·레이아웃으로 변환해 편집 가능 덱 생성
- Sheets: 각 행의 데이터로 태스크 실행, 결과 시트 기록
- Dashboards: DB 스키마 읽어 SQL 쿼리 작성, 대시보드 차트 구동
- Videos: 브리핑을 샷 플랜으로 변환, 비디오 도구 호출해 타임라인 클립 생성
https://github.com/HarnessRouter/starter-kit
관련 노트
- threads-44646b794b312d43617877 — 최초 언급 스레드 (HarnessRouter 소개, @unclejobs.ai, 2026-09-22)
- harness — 에이전트 하네스 상위 개념
- deepseek-harness — DeepSeek Harness (Cordis 기반 플러그인 하네스, 비교 대상)
- Claude Code — Claude Code MOC
- codex — OpenAI Codex CLI 엔티티
- openrouter — 모델 통합의 유사 사례 (모델 vs 하네스 방향 차이)
- openai-agents-api — OpenAI가 Codex 하네스를 관리형으로 제공한 사례
- moc-ai-agents-harness — 하네스 설계·자가개선 MOC
- moc-ai-coding-ops-console — 코딩 에이전트 운영 콘솔 MOC (HarnessRouter Console 해당)
- moc-ai-coding — AI 코딩 운영 상위 MOC