튜토리얼 16: Docker 배포

헤르메스 탐험가 여러분, 다시 환영합니다! 지난 튜토리얼에서는 Hermes Agent를 우리 머신에서 직접 실행하는 방법을 익혔죠. 오늘은 한 단계 더 나아가서, Hermes를 Docker 컨테이너 안에 넣어볼 거예요. 이렇게 하면 환경을 깔끔하게 유지하고, 이식성도 높이고, 업그레이드도 쉬워지는 게임 체인저가 됩니다.

Docker와 Hermes가 만나는 두 가지 방식

본격적으로 들어가기 전에, Docker와 Hermes Agent가 두 가지 방식으로 함께 작동할 수 있다는 점을 이해하는 게 중요합니다:

Docker 안에서 Hermes 실행 – 에이전트 자체가 컨테이너 안에 살아요. 오늘은 이 방식에 집중할 거예요.
터미널 백엔드로 Docker 사용 – Hermes는 호스트에서 실행되지만, 실행하는 모든 명령은 영구적인 Docker 샌드박스 안에서 이루어집니다. 보안과 격리 측면에서 훌륭하지만, 이건 다음에 다룰 주제예요.

오늘은 1번 방식에 올인합니다. 이 방식의 장점은 모든 데이터(설정, API 키, 세션, 스킬, 메모리)가 호스트의 단일 디렉토리에 저장되고, 컨테이너의 /opt/data에 마운트된다는 거예요. 컨테이너 자체는 상태를 저장하지 않으므로, 새 버전을 가져와서 업그레이드해도 아무것도 잃지 않아요.

빠른 시작: 첫 번째 컨테이너

Hermes가 완전 처음이라면, 데이터 디렉토리를 만들고 셋업 마법사를 대화형으로 실행하는 게 가장 쉬운 방법이에요. API 키를 입력하고 ~/.hermes/.env에 저장하는 과정을 안내해 줄 거예요.

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

주의사항: 브라우저 기반 VPS 콘솔(예: Hetzner Cloud)에서는 이 명령어를 실행하지 마세요. :, @, = 같은 특수문자가 종종 변형되어 docker run 인자를 조용히 망가뜨릴 수 있어요. 항상 SSH(ssh root@<host>)로 접속해서 복사-붙여넣기 안전하게 입력하세요. 브라우저 콘솔을 꼭 써야 한다면 명령어를 수동으로 입력하고 모든 문자를 다시 확인하세요.

마법사에 들어가면 채팅 시스템(Telegram, Discord 등)을 설정하는 걸 강력히 추천해요. 게이트웨이가 메시지를 보낼 곳이 필요하니까요.

게이트웨이 모드로 실행하기

설정이 끝나면 Hermes를 백그라운드 게이트웨이로 상시 실행하게 될 거예요. 이렇게 해야 채팅 플랫폼에 연결되고 24/7 계속 살아있어요.

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

-p 8642:8642 플래그는 게이트웨이의 OpenAI 호환 API 서버와 헬스 엔드포인트를 노출해요. 채팅 플랫폼만 사용한다면 선택 사항이지만, 대시보드나 외부 도구가 게이트웨이에 접근해야 한다면 필수예요.

새로운 기능 소개: 공식 Docker 이미지 안에서 gateway run은 이제 s6-overlay에 의해 자동으로 감독됩니다. 즉, 게이트웨이 프로세스가 충돌해도 컨테이너를 잃지 않고 몇 초 안에 재시작돼요. docker logs에서 업그레이드를 확인하는 빵 부스러기(로그)를 볼 수 있을 거예요. 예전 동작(게이트웨이가 종료되면 컨테이너도 종료되는 방식)을 원한다면 --no-supervise를 전달하거나 HERMES_GATEWAY_NO_SUPERVISE=1을 설정하세요. 프로덕션 환경에서는 감독 모드가 훨씬 더 좋아요.

API 서버 노출하기

기본적으로 API 서버는 API_SERVER_ENABLED=true일 때만 활성화돼요. 컨테이너 내부의 127.0.0.1 밖으로 노출하려면 몇 가지 환경 변수를 설정해야 해요:

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

API_SERVER_KEY는 최소 8자 이상이어야 해요. openssl rand -hex 32로 생성하세요. 중요: 인터넷에 노출된 머신에서 포트를 여는 것은 보안 위험이에요. 그 영향을 완전히 이해하지 못했다면 하지 마세요.

대시보드 실행하기

게이트웨이를 모니터링할 웹 대시보드를 원하세요? HERMES_DASHBOARD=1을 설정하고 포트 9119를 노출하세요:

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가 감독하므로 충돌 시 자동으로 재시작돼요. 출력은 docker logs <container>에서 확인할 수 있어요.

도구 루프 가드레일에 대한 참고사항

무인 게이트웨이에서는 도구 루프 가드레일에 하드 스톱을 활성화하는 것을 고려해 보세요. 기본값은 false인데, 사람이 경고를 볼 수 있는 대화형 세션에서는 괜찮아요. 하지만 무인 게이트웨이에서는 루프에 빠진 에이전트가 영원히 멈추지 않을 수 있어요. 프로필의 config.yaml에 다음을 추가하세요:

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

마무리

이것이 Docker 배포 이야기였어요! 이제 모든 데이터를 호스트에 안전하게 마운트한 상태에서 상태를 저장하지 않는 업그레이드 가능한 컨테이너를 갖게 됐어요. 다음 튜토리얼에서는 대시보드를 더 자세히 살펴볼 거예요. 그때까지, 컨테이너 작업 즐겁게 하세요!