HarnessRouter 셀프 호스팅 및 API 통합 가이드
Codex, Claude Code, Hermes를 하나의 API로 통합하는 HarnessRouter 배포법을 정리합니다. Docker 설정, 루프백 바인딩, 초기 로그인 변경 및 TLS 적용 과정을 상세히 안내합니다.
HarnessRouter가 제거하는 것
HarnessRouter Community Edition을 직접 호스팅하면 소유한 서버에서 여러 에이전트 하네스(agent harness) 앞단에 하나의 API를 배치할 수 있습니다. 에이전트 하네스는 루프 내에서 모델을 구동하는 명령줄 프로그램입니다. 세션을 유지하고, 파일을 편집하고, 명령을 실행하며, 작업 요청자에게 진행 상황을 스트리밍합니다. Codex, Claude Code, Hermes는 각각 이 작업을 수행하며, 각기 다른 설치 방식, 자격 증명 형식, 세션에 대한 정의를 가지고 있습니다. HarnessRouter는 이 모든 것을 하나의 컨테이너 안에서 실행하며, 단일 HTTP 엔드포인트, 단일 로그인, 단일 비밀 저장소를 앞단에 배치합니다.
이것이 전체 개념이며, 그 비용은 명확히 언급할 가치가 있습니다. 여러 움직이는 부품을 하나로 만들기 위해 서버에 컨테이너, 로그인, 볼륨, 업그레이드 경로를 추가하는 것입니다. 오늘 정확히 하나의 하네스만 실행 중이라면, 이는 하네스를 직접 설치하는 것보다 더 나쁜 설정입니다. 그 절충안은 이 문서의 마지막 섹션에 있으므로 배포하기 전에 읽어 보시기 바랍니다.
아래의 모든 내용은 2026년 8월 19일에 풀(pull)한 이미지 태그 0.5.5을 기준으로 확인되었습니다. 프로젝트는 거의 매일 새로운 태그를 게시하므로, 한 달 뒤 이 페이지를 맹신하지 말고 실제로 실행 중인 태그를 확인하십시오. 2026년 11월 8일에 이 페이지는 프로젝트의 최신 문서 및 소스 코드를 기준으로 재확인되었습니다. 당시 latest는 0.38.5을 가리키고 있었으며, 현재 릴리스가 다르게 동작하는 부분은 별도로 명시했습니다. 명령어는 github.com/HarnessRouter/harnessrouter의 프로젝트 저장소에서 가져왔습니다. 해당 내용은 0.5.5의 README에 있었으며, 현재 설정 세부 정보는 동일 저장소의 docs/self-hosting-guide.md에 있습니다.
Unified Harness Protocol의 실체
HarnessRouter는 unifiedharnessprotocol.org에 게시된 Unified Harness Protocol(UHP)을 구현합니다. UHP는 제품이 하니스에서 작업을 시작하고, 실행 중인 작업을 추적하며, 세션과 파일을 관리하고, 실패를 보고하는 방식을 기술합니다. 사양은 날짜별로 버전이 관리됩니다. 2026년 8월 19일 기준 버전은 2026-08-11 날짜가 지정되었습니다. 2026년 11월 8일 기준 해당 사이트는 2026-10-19를 최신 버전으로 나열하며, 여전히 이를 "구축하기에 충분히 안정적이고 안전하게 변경할 수 있도록 버전이 관리되는" 초안 표준으로 지칭합니다.
여기서 "개방형 표준"이라는 문구를 주의 깊게 읽어야 합니다. 동일한 회사가 사양, 참조 구현, 그리고 누가 준수하는지 결정하는 적합성 제품군을 모두 작성하며, 프로젝트의 거버넌스 규칙에 따르면 이 세 가지가 모두 함께 이동하지 않는 한 변경 사항은 적용되지 않습니다. 2026년 11월 9일 기준, 프로토콜 홈페이지는 해당 제품군을 110개의 실행 가능한 검사 항목으로 설명하지만, 적합성 페이지는 101개라고 명시하며, 2026년 9월 4일자 자가 호스팅 가이드의 기록된 참조 실행은 64개를 통과했으므로 게시된 수치는 서로 일치하지 않습니다. 프로젝트의 변경 로그는 6개의 추가 분기 검사 항목을 2026년 11월 4일로 기록합니다. 이는 이 정도로 초기 단계인 프로토콜에서는 일반적인 현상이며, Apache-2.0 라이선스는 해당 코드의 어떤 부분이든 포크할 수 있음을 의미합니다. 또한 이는 UHP가 아직 다중 공급업체 표준이 아님을 의미합니다. 이를 유용하고 변화하는 신흥 프로토콜로 간주하고, 귀하의 코드가 재작성 없이도 사용을 중단할 수 있도록 설계하십시오.
시작하기 전에 필요한 것
Docker와 약 4 GB의 여유 디스크 공간이 필요합니다. 또한 이미 비용을 지불하고 있는 모델 제공업체의 API 키가 있어야 합니다. 이미지 다운로드 용량은 약 700 MB이며, 나머지 디스크 공간은 에이전트 CLI와 에이전트가 작업 내용을 기록하는 작업 공간(workspace)에서 사용합니다. 이미지 내부에는 번들로 제공되는 모델이나 체험용 키가 포함되어 있지 않으므로, 제공업체를 연결하기 전까지는 작업이 실패합니다. HarnessRouter 자체는 Apache-2.0 라이선스를 따릅니다. 에이전트 CLI는 각자의 라이선스 및 약관을 따르며, 저장소의 라이선스가 이를 대체하지 않습니다. 에이전트 CLI는 이미지에 포함되어 배포되지 않고 최초 실행 시점에 가져옵니다.
docker run 한 번으로 HarnessRouter 자체 호스팅하기
docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter그다음 컨테이너가 올라오는 것을 확인합니다. 첫 시작은 느리며, 로그를 통해 그 이유를 알 수 있습니다.
docker logs -f harnessrouter작업이 진행되는 동안 다음과 같은 줄이 나타납니다.
installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…ready on :3000이 나올 때까지 기다립니다. 현재 가이드는 docker run가 프롬프트를 반환한 시점부터 대략 30초 정도 소요되는 것으로 측정합니다. 해당 줄이 나온 직후 http://localhost:3000가 즉시 응답하지 않는다면 몇 초 뒤에 다시 시도하십시오. 설치된 CLI는 볼륨에 캐시되므로 이후 시작은 보통 훨씬 빠릅니다. 다만 나중에 추가하는 백엔드나 이전에 설치에 실패했던 백엔드는 여전히 설치 작업을 유발할 수 있습니다.
이 다운로드 과정에서 두 가지 사실이 도출되며, 둘 다 VPS 환경에서 중요합니다. 첫째, 첫 부팅 시 아웃바운드 네트워크 접근이 필요합니다. 이미지가 모든 것을 포함하고 있지 않으므로, 송신 필터(egress filter) 뒤에 있거나 외부 경로가 없는 서버는 에이전트 CLI를 가져올 수 없습니다. 0.5.5과 현재 릴리스 모두 설치 실패를 치명적인 오류로 간주하지 않고 로그에 명시하므로, backends available: 줄에서 어떤 백엔드가 제외되었는지 확인하십시오. 둘째, 귀하는 제3자의 약관에 따라 제3자의 소프트웨어를 설치하는 것입니다. Claude Code는 Anthropic의 약관을 따르며 Hermes는 해당 업스트림의 약관을 따르므로, 상업적으로 사용하기 전에 두 약관을 모두 확인하십시오.
-v harnessrouter:/data은 명명된 Docker 볼륨을 생성합니다. SQLite 데이터베이스, 저장된 파일, 비밀 저장소, 에이전트 작업 공간 등 모든 영구 데이터는 /data에 저장됩니다. 이 볼륨을 삭제하면 제공자 키와 모든 대화 기록을 포함하여 인스턴스 자체가 삭제됩니다. 컨테이너를 중지한 상태에서 백업하십시오. SQLite 데이터베이스가 기록되는 도중에 복사하면 파일을 열 수 없는 상태가 될 수 있기 때문입니다. 이 '중지 후 복사' 원칙은 서버의 모든 상태 유지 컨테이너에 적용됩니다. 다만 서비스마다 세부 사항이 다르므로 PhotoPrism 및 Immich와 같이 각자 고유한 백업 명령이 필요한 경우도 있습니다.
docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouterCompose 변형 및 변경해야 할 행
저장소는 compose 파일을 제공합니다. 현재 "127.0.0.1:3000:3000"를 게시하며 호스트 포트를 루프백에 바인딩합니다. 0.5.5 파일은 "3000:3000"를 게시했습니다. 공개 서버에서 이전 파일을 사용하는 경우 해당 행을 변경하십시오.
services:
harnessrouter:
image: harnessrouter/harnessrouter:0.5.5
ports:
- "127.0.0.1:3000:3000"
env_file:
- .env
volumes:
- harnessrouter-data:/data
restart: unless-stopped
volumes:
harnessrouter-data:현재 업스트림과 다른 점은 latest 대신 고정된 버전 태그를 사용한다는 것입니다. 릴리스가 빠르게 변경되므로 고정은 중요합니다. 2026년 11월 8일 확인 결과, Docker Hub는 0.38.4과 0.38.5 모두 지난 하루 동안 푸시된 것으로 나열했습니다. 사용자의 환경에서 변경되는 에이전트 런타임은 디버깅하기 어렵습니다. 이 페이지에서 0.5.5를 복사하는 대신 현재 릴리스를 고정하십시오. 2026년 11월 9일 기준 해당 값은 0.40.0이었습니다. 그런 다음 환경 파일을 복사하고 권한을 잠근 후 시작하십시오.
cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f.env은 공급자 키를 일반 텍스트로 보관하므로 모드 600이 최소 요구 사항입니다. docker compose 하위 명령이 익숙하지 않다면 Docker Compose 명령 치트 시트에서 일상적인 명령어를 확인하십시오.
포트가 0.0.0.0이 아닌 127.0.0.1에 게시되는 이유
-p 3000:3000은 기본적으로 호스트가 가진 모든 인터페이스에 포트를 게시합니다. -p 127.0.0.1:3000:3000은 호스트 포트를 루프백에 게시합니다. 28.0.0 이전의 Docker 릴리스에서는 동일한 L2 세그먼트에 있는 호스트가 루프백으로 게시된 포트에 접근할 수 있으며, 직접 라우팅이 명시적으로 활성화된 경우 루프백 호스트 매핑에도 불구하고 컨테이너 포트가 노출될 수 있습니다. 컨테이너는 기본적으로 내부 3000번 포트에서 수신 대기하며, 이는 PORT을 통해 설정할 수 있으므로 호스트 포트 충돌을 피하려면 왼쪽 포트 번호를 변경하십시오. 현재 상태를 확인하십시오:
docker port harnessrouter
sudo ss -ltnp | grep 3000ss가 127.0.0.1:3000를 출력하는 것이 올바릅니다. 0.0.0.0:3000은 콘솔이 모든 IPv4 인터페이스에 바인딩되었음을 의미하며, 공용 인터넷 접근 여부는 여전히 라우팅 및 필터링 설정에 따라 결정됩니다. 이 경우 콘솔이 하네스를 생성하고, 모든 기록을 읽으며, 에이전트를 실행하고, 해당 에이전트에게 작업 공간 내의 셸과 실제 파일 시스템에 대한 접근 권한을 부여하기 때문에 대부분의 자체 호스팅 애플리케이션보다 위험합니다. 또한 연결된 공급자 키를 보유하고 있습니다. 보호되지 않은 콘솔에 접근하는 사람은 누구나 사용자의 작업을 읽고, 명령을 실행하며, 키를 사용할 수 있습니다.
ufw 거부 규칙은 이를 방지하지 못합니다. Docker는 ufw이 관리하는 체인보다 먼저 자체 규칙을 통해 게시된 컨테이너 트래픽을 우회시키므로, sudo ufw status에서 포트가 거부된 것으로 표시되더라도 게시된 포트가 차단되었다고 단정할 수 없습니다. VPS 내부가 아닌 다른 기기에서 테스트하십시오. 그렇지 않으면 아무것도 테스트할 수 없습니다. 이는 포트 3080에서 dsh를 헤드리스로 실행하기와 같은 교훈을 줍니다. 서비스를 루프백에 바인딩한 다음, 어떻게 접근할지 신중하게 결정하십시오.
기본 로그인 정보를 가장 먼저 변경하십시오
http://localhost:3000에 사용자 이름 harnessrouter과 인스턴스에서 생성된 초기 비밀번호로 로그인하십시오. 다음 명령으로 비밀번호를 확인할 수 있습니다.
docker exec harnessrouter cat /data/selfhost-initial-password공유 비밀번호인 harnessrouter는 0.5.5에서 사용되었으나, 현재 설치 버전에서는 해당 기본값을 허용하지 않습니다.
프로필 페이지에서 비밀번호를 변경하거나, 스크립트를 통한 배포 시 시작 단계에서 설정하십시오. HR_AUTH_USER와 HR_AUTH_PASSWORD를 통해 초기 자격 증명을 제공할 수 있으며, 프로필에서 저장한 자격 증명이 우선 적용됩니다.
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로컬 콘솔 로그인에는 비밀번호 재설정을 위한 이메일 기능이 없습니다. 비밀번호를 분실한 경우 볼륨 내 인증 파일을 삭제하고 재시작하십시오. 그 후 직접 설정한 HR_AUTH_USER과 HR_AUTH_PASSWORD로 로그인하거나, 별도로 설정하지 않았다면 생성된 초기 비밀번호를 사용하십시오.
docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouterHR_AUTH_DISABLED=1은 로그인 관문을 완전히 제거합니다. 셀프 호스팅 가이드에서는 이를 "아무도 접근할 수 없는 기기에서만 합리적"이라고 설명합니다. 공인 IP 주소를 가진 VPS는 이에 해당하지 않으므로, 노트북에서 실행하는 경우가 아니라면 로그인 관문을 그대로 유지하십시오.
버전을 확인하십시오. 이전 버전에는 인증 관문이 없습니다
이 부분은 심각하게 고려해야 합니다. 0.1.x 및 0.2.0 버전은 인증 관문이 전혀 없는 상태로 출시되었습니다. 포트 3000에 접근할 수 있는 사람은 누구나 콘솔에 접속할 수 있었습니다. 0.3.0은 로그인 기능이 포함된 첫 번째 릴리스입니다. 이 페이지는 해당 이전 태그들이 2026년 10월 12일에 게시되어 가져올 수 있었음을 마지막으로 기록했습니다. 2026년 11월 8일 기준으로 현재 사용 가능 여부는 확인되지 않았습니다.
2026년 8월 19일 기준으로 가장 최근에 게시된 태그는 2026년 8월 18일자 0.5.5입니다. 2026년 11월 8일 기준으로 latest은 0.38.5를 가리키고 있습니다. 현재 사용 중인 버전을 확인한 뒤 Docker Hub의 태그 목록과 비교하십시오.
docker image ls harnessrouter/harnessrouter0.3.0 미만의 모든 버전은 일정을 잡을 것이 아니라 즉시 교체해야 합니다. 공유 기본 비밀번호를 사용하는 이전 릴리스는 여전히 비밀번호 변경이 필요합니다. 현재 설치 버전은 초기 비밀번호를 생성하며 사용자에게 직접 비밀번호를 설정하도록 요구합니다. 이 페이지의 버전 번호를 최신 정보로 간주하지 마십시오. 해당 날짜에는 사실이었으나, 이 프로젝트는 빠르게 릴리스됩니다.
공급자 연결
모델 공급자가 연결되기 전까지는 아무것도 실행되지 않습니다. 계정 메뉴의 Bring your own key에서 공급자를 추가하거나 환경 변수의 docker run에 전달하십시오. 값은 JSON 형식이므로 셸에서 따옴표로 묶으십시오.
-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'.env.example는 공급자 제품군당 하나의 연결 변수를 지정합니다. claude-code 백엔드에는 HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC, codex 백엔드에는 HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI, gemini 백엔드에는 HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE, 그리고 집계기나 자체 추론 서버가 위치하는 모든 OpenAI 호환 엔드포인트에는 HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM을 사용합니다. 일치하는 HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE, HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX, HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES 변수는 각 백엔드가 기본적으로 사용하는 연결을 지정하며, 백엔드당 하나의 정책 변수가 있습니다. HR_SECRET_KEY는 별개의 항목입니다. 현재 릴리스는 저장된 자격 증명을 이 변수를 사용하여 암호화하며, 값을 제공하지 않으면 /data/secret-key에 키를 생성합니다. 재시작 및 업그레이드 전반에 걸쳐 동일한 키를 유지하십시오. 기존 인스턴스의 데이터와 분리하려면 HR_SECRET_KEY를 해당 파일의 값으로 설정하고 파일을 삭제하십시오.
HR_BACKENDS는 HR_BACKENDS=claude,codex,hermes과 같이 설치 및 로드할 백엔드를 선택합니다. 설정하지 않으면 현재 릴리스는 claude, codex, hermes부터 opencode, gemini, goose 등에 이르기까지 30개의 백엔드로 구성된 훨씬 긴 기본 목록을 설치하므로, 이를 줄이면 디스크 공간과 초기 시작 시간을 절약할 수 있습니다. 현재 자가 호스팅 가이드에서는 "사용하지 않을 경우 HR_BACKENDS에서 제외하라"고 조언하며, 자체적인 간소화 예시는 Hermes를 완전히 제외한 HR_BACKENDS=opencode입니다. 백엔드 설치 실패는 치명적이지 않습니다. 다른 백엔드는 정상 작동하며, 설치되지 않은 백엔드에서 작업을 수행하면 "not installed"로 거부되고 컨테이너 로그에 실패한 설치 항목이 표시됩니다. 0.5.5 README에는 hermes을 제외할 경우 컨테이너가 오류 메시지 없이 상태 코드 1로 즉시 종료되는 알려진 문제가 있었으나, 해당 태그의 진입점(entrypoint)은 이미 이 문제를 해결했습니다. 주석에는 이전 구현 방식이 설명되어 있습니다. Hermes만 필요한 하니스로 사용하려면 Hermes 에이전트를 별도의 VPS에서 실행하는 것이 더 작은 규모의 배포 방식입니다.
콘솔 없이 API 호출하기
콘솔은 선택 사항입니다. 동일한 API가 양쪽 모두를 지원하며, Responses 스타일의 계약을 따릅니다. 먼저 로그인하여 세션 쿠키를 획득하십시오:
curl -c hr.cookies http://localhost:3000/api/selfhost/login \
-H 'content-type: application/json' \
-d '{"username":"harnessrouter","password":"your-password"}'그런 다음 metadata.harness_id에 하네스 이름을 지정하고 연결된 공급자가 실제로 제공하는 모델을 사용하여 작업을 전송하십시오:
curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
-H 'content-type: application/json' \
-d '{"input":"Reply with exactly this and nothing else: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt-5.4-mini",
"stream":false}'출력 블록과 토큰 수를 포함하는 JSON 객체가 반환되면 하네스가 정상적으로 실행된 것입니다. harness_id를 codex에서 claude-code로 변경하면 동일한 요청이 다른 하네스로 전송되며, 이 교체 작업이 바로 이 소프트웨어가 존재하는 이유입니다. HR_BACKENDS의 백엔드 이름과 claude의 정책 변수에도 불구하고 ID는 claude-code이라는 점에 유의하십시오. 위와 같은 사용자 지정 연결 방식은 VPS에서 자체 호스팅하는 DeepSeek 하네스를 연결하는 것처럼, 이미 호스팅 중인 OpenAI 호환 엔드포인트로 하네스를 지정하는 방법입니다.
세션 쿠키 흐름은 로컬 디버깅을 위해 계속 지원됩니다. 제품 백엔드의 경우, 현재 문서에서는 콘솔 세션을 유지하는 대신 API Keys에서 HarnessRouter API 키를 생성하여 Bearer 토큰으로 전송할 것을 권장합니다.
포트를 공개하지 않고 노트북에서 접속하기
두 가지 방법이 있으며, 어느 쪽도 0.0.0.0에 포트를 직접 노출하지 않습니다.
SSH 터널은 가장 비용이 적게 드는 방법이며, 서버에 별도의 소프트웨어를 설치할 필요가 없습니다. 이 방법은 로컬 머신의 포트를 VPS의 루프백 주소로 전달합니다.
ssh -N -L 3000:127.0.0.1:3000 you@your-vps이 명령을 실행해 둔 상태에서 브라우저로 http://localhost:3000에 접속합니다. 만약 SSH가 bind: Address already in use 오류를 출력한다면, 노트북의 3000번 포트를 이미 다른 프로세스가 사용 중인 것입니다. 이 경우 -L 3100:127.0.0.1:3000를 사용하여 다른 로컬 포트를 선택한 뒤 3100번 포트로 접속하십시오.
종단 리버스 프록시는 다른 사용자의 접근이 필요할 때 사용하는 방법입니다. 프록시가 TLS(전송 계층 보안) 인증서를 관리하고 루프백 주소로 요청을 전달합니다. 자가 호스팅 가이드에서 제공하는 Caddy 설정은 다음과 같습니다.
console.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000 {
flush_interval -1 # agent turns stream for minutes; never buffer them
}
}flush_interval -1는 Caddy의 응답 버퍼링을 명시적으로 비활성화합니다. Caddy는 이 설정이 없어도 text/event-stream 응답을 즉시 전송합니다. 에이전트는 수 분 동안 스트림 토큰을 생성하는데, 응답을 버퍼링하는 프록시는 토큰 생성이 끝날 때까지 데이터를 붙잡아 둡니다. 이로 인해 콘솔 화면이 멈춘 것처럼 보이다가 한꺼번에 모든 내용이 출력되는 현상이 발생합니다. Nginx에서는 location 블록 안에 proxy_buffering off;을 설정하여 동일한 효과를 낼 수 있습니다. 어떤 프록시를 선택하든 DNS 이름은 프록시를 가리키게 하고, 컨테이너는 루프백 주소에서 실행되도록 구성하십시오. 리버스 프록시로서의 Nginx, Caddy, Traefik 비교 문서에서 각 환경에 적합한 도구를 확인할 수 있습니다.
root가 아닌 전용 사용자로 실행하기
Docker daemon은 root 권한으로 실행되며, docker 그룹의 멤버십은 root 권한과 동일합니다. 해당 그룹의 구성원은 호스트 파일 시스템을 마운트하는 컨테이너를 시작할 수 있기 때문입니다. 따라서 "팀원을 docker 그룹에 추가"하는 행위는 공급자 키가 저장된 서버의 root 권한을 넘겨주는 것과 같습니다.
간단한 방법은 compose 파일과 .env를 소유하는 서비스 계정을 생성하고, 해당 파일들을 공유 홈 디렉터리에 두지 않는 것입니다.
sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter--user을 docker run에 추가하거나 compose 파일에 user:를 추가하여 해결하려 하지 마십시오. 현재 가이드는 컨테이너가 반드시 root로 시작해야 한다고 명시하고 있으며, 0.8.2부터는 다른 방식으로 시작하려 할 경우 로그에 관련 내용을 한 줄 남기고 실행을 거부합니다.
더 강력한 방법은 rootless Docker를 사용하는 것입니다. 이 방식에서는 daemon 자체가 권한이 없는 일반 사용자로 실행됩니다. 이를 위해서는 newuidmap 및 newgidmap을 위한 uidmap 패키지가 필요하며, 해당 사용자에 대해 /etc/subuid 및 /etc/subgid 내에 최소 65536개의 하위 UID가 할당되어 있어야 합니다. uidmap는 Ubuntu 아카이브에 포함되어 있지만, docker-ce-rootless-extras은 그렇지 않습니다. 이는 Docker의 공식 apt 저장소인 download.docker.com에서 제공하며, Docker engine 설치 시 해당 저장소가 추가됩니다. 만약 해당 저장소에서 engine을 설치하지 않았다면 grep -rl download.docker.com /etc/apt/sources.list.d/은 아무것도 출력하지 않으며, 아래의 설치 과정에서 패키지를 찾을 수 없습니다.
sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now dockerloginctl enable-linger는 사용자가 로그아웃한 후에도 systemd 인스턴스가 계속 실행되도록 유지하며 부팅 시점에 이를 시작합니다. docker info 명령을 실행하여 Security Options 항목 아래에 rootless가 표시되는지 확인하십시오. Rootless 모드는 추가 설정 없이는 1024 미만의 포트를 바인딩할 수 없지만, 여기서는 포트 3000을 사용하므로 문제가 되지 않습니다. 계정 설정 자체는 VPS에서 최소 권한 사용자 생성하기를 참조하십시오.
오류 발생 시 현상과 확인 방법
컨테이너가 시작 후 1초 만에 종료되고 로그가 비어 있습니다. docker ps -a는 Exited (1)을 보여줍니다. HR_BACKENDS에서 hermes을 누락했을 때 이전 엔트리포인트가 실패했으나, README에는 여전히 해당 문제가 기재되어 있음에도 0.5.5에는 이미 수정 사항이 포함되어 있습니다. 종료 상태 코드만으로 해당 실패를 진단하지 마십시오. 최근 태그에서 docker logs의 마지막 줄을 읽어보면, 0.8.2부터 --user로 시작된 컨테이너가 root 권한으로 시작해야 한다는 한 줄의 메시지를 남기고 종료됩니다.
첫 시작이 완료되지 않습니다. 로그가 installing 줄 이후 멈추고 ready on :3000가 나타나지 않습니다. 에이전트 CLI는 이미지에 포함되어 있지 않으므로, 서버가 네트워크에 연결되어 이를 가져올 수 있는지 확인하십시오. 0.5.5와 현재 릴리스 모두 설치 실패를 허용하며, 로그에 실패한 설치 항목을 기록하고 backends available: 줄에서는 제외합니다. 아웃바운드 경로 또는 프록시 설정을 수정한 뒤 재시작하십시오.
콘솔은 로드되지만 모든 작업이 실패합니다. 연결된 공급자가 없습니다. 이미지 내에 번들로 제공되는 모델이나 무료 티어는 없으므로, 새로 설치한 인스턴스는 로그인할 수 있어도 아무것도 실행하지 못할 수 있습니다.
프록시 뒤에서 콘솔이 답변 도중 멈춥니다. 응답이 끝날 때 출력 내용이 한꺼번에 나타납니다. 이는 응답 버퍼링 때문입니다. Caddy에서는 flush_interval -1을, Nginx에서는 proxy_buffering off;을 설정하십시오.
터널은 연결되어 있으나 노트북에서 접근할 수 없습니다. 서버에서 docker port harnessrouter를 실행하십시오. 아무것도 출력되지 않는다면 컨테이너가 포트를 게시하지 않은 것이므로, 포트 매핑과 네트워크 모드를 확인하십시오.
실행할 가치가 있습니까?
여러 개의 하네스를 실제로 사용하고 있으며, 각각 3개씩 필요한 엔드포인트와 자격 증명 저장소를 하나로 통합하고 싶다면 실행할 가치가 있습니다. 또한, 그 위에 제품을 구축하고 있으며 하네스를 코드 재작성 대신 설정 값으로 관리하고 싶을 때도 유용합니다. 이것이 UHP가 제공하는 이점이지만, 프로토콜이 아직 초기 단계라는 점은 유의해야 합니다.
하네스를 하나만 사용한다면 실행할 가치가 없습니다. 서버에 해당 CLI를 설치하는 것이 구성 요소가 더 적고, 로그인 과정 없이 바로 접근할 수 있기 때문입니다. 또한 여러 하네스 앞에 API 하나를 두는 것이 아니라, 여러 에이전트가 하나의 작업에 협력하는 형태를 원한다면 이 도구는 적합하지 않습니다. 그러한 패턴은 Omnigent와 같은 멀티 에이전트 하네스를 참조하십시오. 어떤 경우든 배포 규칙은 변하지 않습니다. 루프백 바인딩, 변경된 비밀번호, 고정된 현재 릴리스, 그리고 전용 사용자 계정을 사용하십시오.
FAQ
HarnessRouter를 3000번 포트로 공개해도 안전합니까?
아니요. 콘솔은 하네스를 생성하고, 모든 기록을 읽으며, 셸 및 파일 시스템 접근 권한을 가진 에이전트를 실행하고, 연결된 공급자 키를 보관하므로 보호되지 않은 콘솔은 이 모든 정보를 노출합니다. -p 127.0.0.1:3000:3000을 사용하여 루프백 인터페이스에서 실행하고 SSH 터널이나 TLS 종료 리버스 프록시를 통해 접근하십시오. ufw 거부 규칙만으로는 충분하지 않습니다. Docker는 ufw가 관리하는 체인보다 먼저 게시된 컨테이너 트래픽을 우회하기 때문입니다. sudo ss -ltnp | grep 3000으로 확인하십시오. 이 명령은 127.0.0.1:3000를 출력해야 하며, 다른 머신에서 접근을 테스트해야 합니다. 이전 버전의 localhost 노출 문제를 피하려면 Docker 28.0.0 이상을 사용하고, 직접 라우팅이 활성화되지 않았는지 확인하십시오.
로그인 게이트가 추가된 HarnessRouter 버전은 무엇입니까?
0.3.0입니다. 버전 0.1.x과 0.2.0은 인증 기능 없이 배포되었으므로, 해당 버전을 실행하는 사용자는 아무도 포트를 발견하지 못할 것이라는 가정에 의존하고 있습니다. 이 페이지에서 마지막으로 기록한 해당 태그의 게시 및 풀 가능 날짜는 2026년 10월 12일이며, 2026년 11월 8일 기준으로 현재 사용 가능 여부는 확인되지 않았습니다. 2026년 8월 19일 기준 최신 태그는 2026년 8월 18일자 0.5.5였으며, 2026년 11월 8일에는 latest이 0.38.5을 가리키고 있었습니다. docker image ls harnessrouter/harnessrouter를 실행하여 현재 버전을 확인하고, 이 페이지가 아닌 Docker Hub의 태그 목록과 비교하여 직접 비밀번호를 설정하십시오. 현재 설치 버전은 기존의 공유 기본값을 사용하는 대신 초기 비밀번호를 생성합니다.
HR_BACKENDS를 설정한 직후 컨테이너가 종료되는 이유는 무엇입니까?
현재 릴리스에서는 종료되지 않아야 합니다. 셀프 호스팅 가이드에 따르면 사용하지 않는 백엔드는 제외해야 하며, 설치에 실패한 백엔드가 있다고 해서 치명적인 오류가 발생하지는 않습니다. 이전 구현에서는 hermes이 누락되면 오류 메시지 없이 상태 코드 1로 종료되었으나, 0.5.5 소스에서는 README에 여전히 해당 내용이 기재되어 있음에도 불구하고 이미 이 오류가 수정되었습니다. 최근 태그의 경우 docker logs를 읽어보십시오. 0.8.2부터는 --user로 시작된 컨테이너가 root 권한으로 시작해야 한다는 메시지를 한 줄 출력하고 종료됩니다.
HarnessRouter는 첫 시작 시 인터넷 연결이 필요합니까?
네. 에이전트 CLI는 이미지에 포함되지 않고 첫 시작 시 가져오며, 각 CLI는 자체 라이선스 및 약관의 적용을 받습니다. 0.5.5과 현재 릴리스 모두 로그에 설치 실패 항목을 기록하고 나머지 백엔드는 시작되도록 합니다. 설치된 CLI는 볼륨에 캐시되므로 이후 시작은 일반적으로 더 빠릅니다. 단, 백엔드 도구와 실행하는 작업은 여전히 네트워크 접근이 필요할 수 있으며, 새로운 백엔드나 이전에 실패했던 백엔드는 다시 설치를 트리거할 수 있습니다.
콘솔 비밀번호를 분실했습니다. 어떻게 다시 접속합니까?
로컬 콘솔 로그인을 위한 비밀번호 재설정 이메일 기능은 없습니다. 컨테이너를 중지하고 볼륨에서 /data/selfhost-auth.json를 삭제한 뒤 컨테이너를 다시 시작하십시오. 그 후 직접 설정한 HR_AUTH_USER 및 HR_AUTH_PASSWORD로 로그인하거나, 직접 설정하지 않았다면 생성된 초기 비밀번호로 로그인한 뒤 프로필 페이지에서 새 비밀번호를 설정하십시오. 컨테이너와 볼륨 이름이 모두 harnessrouter인 경우, docker stop harnessrouter을 실행한 뒤 docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json를 수행하고 docker start harnessrouter를 진행하십시오. 생성된 비밀번호는 docker exec harnessrouter cat /data/selfhost-initial-password으로 읽을 수 있습니다.