| 한눈에 보기 | |
|---|---|
| 저장소 | HarnessRouter/harnessrouter |
| 개발 | HarnessRouter (조직) |
| GitHub 스타 | 3,663 (오늘 +95) |
| GitHub 트렌딩 | 일간 Python 16위 |
| 포크 | 393 |
| 주 언어 | Python |
| 라이선스 | Apache-2.0 |
| 공개일 | 2026-08-09 |
| 최신 릴리스 | v0.37.1 (2026-10-26) |
에이전트 제품을 만들 때 가장 번거로운 부분은 모델 호출이 아니라 하네스(harness) 운영이다. Codex나 Claude Code 같은 코딩 에이전트는 각자 실행 방식과 출력 형식, 세션 관리법이 다르다. HarnessRouter/harnessrouter는 이 차이를 하나의 인터페이스로 흡수하는 자체 호스팅 프로젝트다. 하네스라우터 조직이 만들었고, 일간 파이썬 트렌딩 16위에 올라 있다. 하루 스타가 95개 늘어 관심이 빠르게 커지는 중이다.
무엇을 하나: 하네스 통합 API
핵심은 기존 하네스를 '꽂아 쓰는 에이전트 백엔드'로 바꾸는 것이다. 제품 코드는 하네스별 CLI를 직접 다루지 않고 API 한 곳만 호출한다.
- OpenAI Responses 호환 API로 작업 실행, 결과 조회, 하네스 전환
- 지속 세션, 스트리밍 진행 상황, 파일·산출물, 작업 취소, 구조화된 실패 응답
- 공개 표준인 통합 하네스 프로토콜(Unified Harness Protocol, UHP) 구현
- W3C 트레이스 컨텍스트(
traceparent) 전달,Idempotency-Key를 이용한 중복 실행 방지
README에 따르면 현재 지원하는 하네스 베이스는 Codex, Claude Code, Hermes, Pi, OpenCode, Gemini CLI, Cline, goose, Aider, OpenHands 등 26개다. 하네스와 모델 조합을 바꿔 가며 비용과 지연 시간을 비교할 수 있다는 점도 내세운다. 개발팀은 같은 작업에서 가장 싸거나 빠른 조합이 작업마다 다르다고 설명한다.
작동 방식·구조
구조는 콘솔(Console), 게이트웨이(Gateway), 러너(Runner)로 나뉜다. README 설명으로는 콘솔과 게이트웨이는 권한 없는 사용자로 돌고, 러너는 루트 권한으로 세션마다 별도 사용자를 만들어 에이전트 프로세스를 그 사용자로 실행한다. 이 때문에 도커 실행 시 --user 옵션을 쓰지 말라고 안내한다.
하네스의 env 맵에는 요청 헤더($headers.X-Name)나 저장된 비밀값(vault:name)을 연결할 수 있다. 이렇게 주입한 값은 응답, 스트림, 트레이스, 저장 기록에서 가려진다. 다만 README는 에이전트가 읽을 수 있는 값은 외부로 보낼 수도 있다며, 사용자·작업 범위의 단기 최소 권한 토큰을 쓰라고 경고한다.
써보면
도커와 약 4GB 디스크, 모델 제공사 API 키가 필요하다. 계정 가입은 필요 없고 번들 모델이나 체험 키도 없다.
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
첫 실행 때 활성화된 하네스 CLI를 설치하며, 로그에 ready 메시지가 뜨면 localhost:3000에 접속한다. 초기 계정은 harnessrouter/harnessrouter이므로 바로 비밀번호를 바꿔야 한다. 콘솔에서 'Bring your own key'로 키를 넣고, API Keys 메뉴에서 발급한 키로 호출한다.
curl -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}'
metadata.harness_id 값만 바꾸면 다른 하네스로 같은 작업을 보낼 수 있다.
최근 업데이트
최신 릴리스는 v0.37.1이다.
- fast-agent와 Deep Agents Code가 턴이 끝날 때 몰아서가 아니라 단계마다 결과를 실시간으로 보여 준다. 4초짜리 명령 두 개를 실행하는 시험에서 fast-agent의 첫 명령 표시 시간이 16.6초에서 7.5초로 줄었다고 밝혔다.
- 이미지를 받지 못하는 텍스트 전용 모델로 바꿔도 fast-agent 대화가 끊기지 않도록, 해당 모델에서는 이미지를 대화에서 빼고 그 사실을 안내한다.
- 한 번이라도 단독으로 실패한 모델은 해당 베이스에서 제공하지 않는다. 이번 측정에서 fast-agent는 53개 중 51개, Deep Agents Code는 54개 중 53개 모델이 통과했다고 한다.
- 스타터 킷의 body-parser를 2.4.0으로 올려 보안 권고(GHSA-27r3-jxmh-p828)에 대응했다.
누구에게 유용한가
코딩 에이전트를 자사 제품의 백엔드로 붙이려는 SaaS 개발팀, 여러 하네스의 비용·속도를 비교해 고르려는 플랫폼 팀, 키와 코드를 외부로 내보내기 어려운 조직이 대상이다. 하네스를 바꿔도 제품 코드를 고치지 않아도 되므로 실험과 이관 부담이 줄어든다.
의의와 한계
라이선스는 Apache-2.0이라 상용 활용이 자유롭다. 저장소는 2026년 8월 9일 만들어져 약 2개월밖에 되지 않았지만 릴리스가 v0.37.1까지 빠르게 이어졌다. 다만 0.x 버전이라 API와 프로토콜 변경 가능성을 염두에 둬야 한다. 하네스 설치와 세션별 사용자 관리를 위해 루트 권한 컨테이너가 필요하고, 기본 계정을 바꾸기 전에는 로컬에서만 써야 한다. 이 저장소는 관리형 클라우드 서비스와 병행되는 커뮤니티 에디션이어서 제공 범위 차이는 확인이 필요하다. 하네스별 지원 모델은 지원 매트릭스 문서로 점검하는 편이 안전하다.
