헤르메스(hermes agent) 도커 설치 방법! 2. 도커컴포즈 작성 및 실행 (feat. 맥미니 + 클로드)

맥미니 환경에 헤르메스를 도커형태로 구축하는 포스팅으로 앞서 진행한 최초 설정 마법사와 메신저 연동방법은 아래 2개 포스팅을 참고 하기 바랍니다.

이전포스트:

2026.05.31 - [IT/AI 자동화] - 헤르메스(hermes agent) 도커 설치 방법! 1. 최초 설정 마법사 (feat. 맥미니 + 클로드)

2026.05.31 - [IT/AI 자동화] - 헤르메스(hermes agent) 메신저(텔레그램, 슬랙) 연동 방법

 

1. (가장 중요) 설정 마법사를 왜 먼저 돌려야 하는가?

앞의 포스트에서 최초 설정 마법사를 구성하는 포스팅을 올렸는데 이 부분이 선행되지 않으면 컨테이너가 바로 종료되고 재시작을 무한 반복하는 현상이 발생한다고 한다.

공식 문서도 "컨테이너가 즉시 종료"되는 대표 원인으로 .env 파일이 없거나 잘못된 경우 먼저 대화형으로 실행해 설정을 완료하라고 명시합니다.

그래서 docker-compose로 올리기 전에 마법사를 한 번 돌려 ~/.hermes를 채워야 하고 이 부분은 이전 포스팅에서 다루었다.
2026.05.31 - [IT/AI 자동화] - 헤르메스(hermes agent) 도커 설치 방법! 1. 최초 설정 마법사 (feat. 맥미니 + 클로드)

2. 관리를 위해 헤르메스 설치 경로 변경

나는 여러 도커 컨테이너를 다루면서 docker/ 폴더 아래 이 컨테이너들의 볼륨을 관리하고 있다
그러다 보니 생긴 문제점 ~/.hermes에 설정정보가 들어가있으니 나중에 백업할 때 저 경로를 또 까먹지 말고 복사를 해야하잖아?그래서 헤르메스 설치 경로를 변경하기로 했다.
(기존) ~/.hermes
(변경) /Volumes/docker/hermes

맥의 사용자 홈 경로로 갔는데 .hermes 경로가 보이지 않는다!?
당황하지 말고 커맨드 + 컨트롤 + . 를 누르면 숨겨져있던 폴더가 나오니까 이걸 복사하자

숨겨져있는 .hermess 폴더

헤르메스 폴더를 복사해서 기존 관리하던 경로로 이동을 시켰다.

새로 이전한 hermes 폴더

 

3. 도커 컴포즈 파일 작성(docker-compose.yaml)

도커 컴포즈 파일의 저장위치 원하는 경로(예: ~/hermes/)에 놓으면 되는데
docker/
docker/hermes
docker/docker-compose.yml
이런식으로 도커 폴더를 하나 만들고 이 경로를 기준으로 도커컴포즈와 헤르메스 경로를 두었다
    volumes:
      - ./hermes:/opt/data      # 실제 헤르메스가 설치된 상대경로
* 만약 ~/.hermes 경로 그대로 사용하고 싶다면? 아래와 같이 수정하면 된다.
      - ~/.hermes:/opt/data     # 홈 디렉토리에 설치한 경우

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"   # 게이트웨이 API / 헬스 엔드포인트
      - "127.0.0.1:9119:9119"   # 웹 대시보드
    volumes:
      - ./hermes:/opt/data      # 실제 헤르메스가 설치된 상대경로
    environment:
      - HERMES_DASHBOARD=0      # 웹 대시보드 1:켜기 0:끄기
      - HERMES_DASHBOARD_HOST=0.0.0.0
    shm_size: "1gb"
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

 

• 데이터는 전부 hermes 폴더에 남습니다. /opt/data 볼륨이 모든 Hermes 상태(설정, 키, 세션, 메모리, 스킬)의 단일 소스이며 그렇기 때문에 백업·이전이 필요할 경우 이 폴더만 복사하면 됩니다.
• 포트를 127.0.0.1:로 묶은 이유: 대시보드는 인증 없는 웹 화면이라 외부 노출이 위험합니다. 기본적으로 루프백에 머물러 네트워크 노출을 피하도록 되어 있어, 맥미니 자기 자신에서만 접근하도록 호스트 루프백에 바인딩했습니다. LAN의 다른 기기에서 보려면 0.0.0.0:...로 바꿔야 하지만, 그건 보안 트레이드오프가 있으니 리버스 프록시/인증을 따로 두는 걸 권합니다.
• shm_size: "1gb"는 브라우저 자동화(Playwright)용입니다. Playwright는 공유 메모리가 필요해 shm 크기를 키워야 합니다. 브라우저 도구를 안 쓸 거면 빼도 됩니다.
• 대시보드가 필요 없으면 HERMES_DASHBOARD 줄과 9119 포트를 지우면 됩니다. 주 사용은 메신저 + CLI로도 충분합니다.

4. 도커 컴포즈  기동

docker-compose.yml이 있는 경로에서 터미널을 열고 다음 명령어 실행

docker-compose up -d

 

파인더에서 해당 폴더 우클릭 후 폴더에서 새로운 터미널 열기로 하면 이동된 상태로 터미널이 열린다.

폴더에서 새로운 터미널 열기

5. 헤르메스가 정상적으로 기동됐는지 도커 컨테이너 확인

도커 데스크탑에서 hermes 상태를 보면 된다. 정상적으로 떠있는 모습

6. 헤르메스 점검 doctor 명령어

docker exec -it hermes hermes doctor

클로드 API키가 유효하지 않다고 나왔다.
✗ Anthropic API (invalid API key)

◆ Security Advisories   ✓ No active security advisories ... ◆ API Connectivity   ⚠ OpenRouter API (not configured)                                      ✗ Anthropic API (invalid API key)

해결방법. 터미널을 열고 순서대로 진행하자
1. claude setup-token → 브라우저로 Claude 구독 계정 로그인·승인 → 출력되는 sk-ant-oat... 토큰 전체 복사
2. docker exec -it hermes hermes config set ANTHROPIC_TOKEN "새_토큰_sk-ant-oat..."
3. docker exec -it hermes hermes config set ANTHROPIC_API_KEY ""

해결 됐는지 다시 확인해보자

docker exec -it hermes hermes doctor

그 외 사소한 심볼링 누락 오류들도 있는데 --fix 옵션으로 실행하면 이런 부분들은 다 잡아준다.

docker exec -it hermes hermes doctor --fix

7. 헤르메스 실행

docker exec -it hermes hermes