Docker + Hermes Agent: 두 가지 활용법

Hermes Agent에서 Docker가 어떻게 쓰이는지 궁금했다면, 바로 이곳이 정답입니다. 실제로 이 둘을 함께 사용하는 방법은 두 가지로 나뉘며, docker run을 입력하기 전에 그 차이를 알아두는 것이 좋습니다.

두 가지 Docker 모드

Hermes를 Docker 안에서 실행 — 에이전트 자체가 컨테이너 안에 들어갑니다. 이 가이드의 핵심 내용입니다.
Docker를 터미널 백엔드로 사용 — Hermes는 호스트 머신에서 실행되지만, 에이전트가 실행하는 모든 명령은 단일 영구 Docker 샌드박스 안에서 이루어집니다. 이 샌드박스는 Hermes 프로세스가 살아있는 한 도구 호출, /new, 심지어 서브에이전트를 넘어서도 유지됩니다.

이 글은 첫 번째 방법을 다룹니다. 핵심만 말하면: 모든 데이터(설정, API 키, 세션, 스킬, 메모리)는 호스트의 단일 디렉터리에 저장되며, 컨테이너 내부의 /opt/data에 마운트됩니다. 이미지 자체는 상태를 저장하지 않으므로(stateless), 설정을 잃지 않고 언제든 새 버전을 받을 수 있습니다.

빠른 시작: 첫 설정

처음이라면 데이터 디렉터리를 만들고 컨테이너를 인터랙티브 모드로 실행하여 설정 마법사를 진행하세요:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

이 명령은 마법사로 안내하며, API 키를 입력받아 ~/.hermes/.env에 저장합니다. 이 과정은 한 번만 하면 됩니다. 이 참에 텔레그램이나 디스코드 같은 채팅 시스템도 함께 설정해 두면 게이트웨이가 대화할 곳이 생기니 좋습니다.

⚠️ 주의사항: 브라우저 기반 VPS 콘솔에서 설치 명령을 실행하지 마세요. 일부 제공업체(예: Hetzner)는 특수 문자를 변형시킵니다 — :가 ;로 바뀌거나, @가 잘못 렌더링되고, 붙여넣은 API 키가 조용히 손상될 수 있습니다. 항상 SSH로 접속하여 복사-붙여넣기 안전한 명령 입력을 사용하세요. 브라우저 콘솔을 어쩔 수 없이 써야 한다면 명령을 직접 타이핑하고 모든 :, @, =, /를 다시 확인하세요.

프로 팁: 컨테이너 안에서 hermes setup --portal을 한 번 실행하세요 — 리프레시 토큰이 마운트된 ~/.hermes 볼륨에 영구 저장됩니다.

게이트웨이 모드로 실행

설정이 끝났다면 컨테이너를 백그라운드에서 영구 게이트웨이로 실행하세요:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

포트 8642는 게이트웨이의 OpenAI 호환 API 서버와 헬스 체크 엔드포인트를 노출합니다. 채팅 플랫폼만 사용한다면 선택 사항이지만, 대시보드나 외부 도구가 게이트웨이에 접근하려면 필수입니다.

새로운 기능: 감독형 게이트웨이

큰 변화가 하나 있습니다: 공식 Docker 이미지에서 gateway run은 이제 s6-overlay가 자동으로 감독합니다. 게이트웨이가 충돌하면 컨테이너를 잃지 않고 몇 초 안에 재시작됩니다. 대시보드(활성화된 경우)도 함께 감독됩니다.

docker logs에서 업그레이드를 확인하는 한 줄짜리 표시를 볼 수 있습니다. 이전 동작(컨테이너 종료 = 게이트웨이 종료)으로 되돌리려면 --no-supervise를 전달하거나 HERMES_GATEWAY_NO_SUPERVISE=1을 설정하세요. CI 스모크 테스트에는 유용하지만, 프로덕션에서는 감독형 기본값이 훨씬 낫습니다.

도구 루프 하드 스톱

무인 게이트웨이에서 중요한 설정 하나: tool_loop_guardrails.hard_stop_enabled는 기본값이 false입니다. 사람이 경고를 볼 수 있는 인터랙티브 세션에서는 괜찮습니다. 하지만 무인 배포에서는 경고만으로는 루프에 빠진 에이전트를 멈추지 못할 수 있습니다. 회로 차단기 동작을 원한다면 프로필의 config.yaml에서 활성화하세요:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

API 서버 노출

API 서버는 API_SERVER_ENABLED=true일 때 활성화됩니다. 컨테이너 내부의 127.0.0.1을 넘어 외부로 노출하려면 API_SERVER_HOST=0.0.0.0과 API_SERVER_KEY(최소 8자 — openssl rand -hex 32로 생성)도 설정하세요:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

보안 참고: 인터넷에 노출된 머신에서 포트를 여는 것은 항상 위험합니다. 결과를 완전히 이해하지 못했다면 하지 마세요.

대시보드 실행

내장 웹 대시보드는 같은 컨테이너 안에서 게이트웨이와 함께 s6-rc 서비스로 감독됩니다. HERMES_DASHBOARD=1만 설정하면 됩니다:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

대시보드가 충돌하면 s6-supervise가 짧은 대기 시간 후 자동으로 재시작합니다. 출력은 docker logs <container>에서 확인할 수 있습니다.

로그 위치

전체 라우팅 맵(프로필별 게이트웨이, 대시보드, 부팅 조정기, 컨테이너 전체 docker logs)에 대한 자세한 내용은 문서의 전용 섹션을 확인하세요. 요약하자면: 모든 로그는 결국 docker logs에 도달하지만, 명확한 접두사가 붙어 있어 무엇이 무엇인지 구분할 수 있습니다.

마무리

Docker는 Hermes Agent를 깔끔하고 업그레이드 가능한 방식으로 실행할 수 있게 해줍니다. 컨테이너는 상태를 저장하지 않으며, 데이터는 호스트에 안전하게 보관되고, 새로운 s6 감독 덕분에 게이트웨이는 충돌해도 계속 유지됩니다. 간단한 설정이든 대시보드 + API 서버 조합이든, 위 명령어만 있으면 몇 분 안에 끝납니다.