헤르메스(hermes agent) 도커 설치 방법! 1. 최초 설정 마법사 (feat. 맥미니 + 클로드)

사용환경
 - 맥미니 M4(실리콘 맥)
 - 도커 데스크탑 설치(다운로드 및 설치하면 끝)
  * 도커 데스크탑 환경이라면 윈도우, 맥 크게 상관없으니 윈도우 사용자도 따라하면 된다.

1. 헤르메스 에이전트 이미지 다운로드

#헤르메스 에이전트 이미지 다운로드
docker pull nousresearch/hermes-agent:latest

실리콘 맥(맥 M1~M5 등이 붙은 제품군)을 사용중이라면 호환이 잘되는지 다음 명령어로 확인해보자

#arm64가 나오면 네이티브로 잘 돌아간다. amd64라면 Rosetta 에뮬레이션으로 돌아가므로 속도 등 영향 있음
docker image inspect nousresearch/hermes-agent:latest --format '{{.Architecture}}'

arm64라고 확인됐으니 돌리는데 문제 없겠거니 생각하면 됨..

2. 최초 설정 마법사 실행
데이터 디렉터리를 만들고 대화형으로 설정 마법사를 한 번 돌려야 한다.
이 단계에서 API키를 입력받아 ~/.hermes/.env에 최초 1회 저장.

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

(도커 파일 경로를 따로 관리하는 경우) 원하는 경로에 hermes 폴더를 만들고 setup 후 이 폴더만 잘 관리하면 된다.

#내가 관리하고 있는 도커폴더 아래에 hermes 폴더를 만들고 거기에 설치
cd /Volumes/docker
mkdir -p hermes
docker run -it --rm -v "$PWD/hermes:/opt/data" nousresearch/hermes-agent setup

2.1. Quick setup

2.1. Quick setup 이미지

2.2. Select provider:

 - 기호에 맞게 선택하면 된다. 나는 앤트로픽 선택
 - 설치 후에도 hermes model 명령어로 언제든 provider를 변경할 수 있다. 고민 말고 ㄱㄱ

Select provider 이미지

2.3. Choose authenication method:

 - 클로드 구독이 있으니 1번으로 선택함. 2번은 API키를 발급받아 내가 사용하는 만큼 종량제로 이용하는 경우 해당된다.
  * 앞에서 선택한 provider 별로 내용이 조금씩은 다르지만 대세에는 지장없으니 참고하여 진행

Choose authenication methode 이미지

2.4. To install and authenicate:

현재 진행중인 터미널은 잠시 그대로 두고 새로운 터미널을 열자
1번~4번까지 그대로 따라해도 되는데 맥에 클로드 데스크탑(맥 전용 클로드 프로그램)이 설치 되어 있다면

To install and authenticate 이미지

새로 연 터미널에 아래 명령어를 입력하고 엔터

claude setup-token

자동으로 인터넷 브라우저가 열리는데

claude setup-token 입력 이미지

승인 버튼을 눌러주면 된다

인터넷 브라우저 클로드 연동 이미지

Long-lived authenication token created successfully! 토큰 생성 성공
Your OAuth token의 주황색 토큰을 복사!

생성된 클로드 OAuth token 이미지

2.5. Setup-token

다시 헤르메스 터미널로 돌아와서 복사한 클로드 OAuth token을 붙여넣기 하면 기본 모델을 선택하라고 나온다.

setup-token 이미지

2.6. Select default model:

현재 기준 가장 일반적인 sonnet 4.6을 선택했다. 나중에 언제든지 변경할 수 있으니 고민하지 말고 선택ㄱㄱ

Select default model 이미지

2.7. Select teminal backend:

도커 환경으로 구성할 것이기 때문에 Keep currnt (local)을 선택했다.

Select teminal backend 이미지

조금 더 부연설명하자면..terminal backend는 에이전트가 명령어를 실제로 실행하는 환경을 고르는 단계로
Keep current (local) / Local 추천→ 에이전트가 지금 이 컨테이너 안에서 직접 명령을 실행합니다. 가장 단순하고, 이미 격리된 컨테이너라 안전 측면도 나쁘지 않다.
Docker → 컨테이너 안에서 또 다른 Docker를 띄우는 구조(docker-in-docker)라 별도 설정 없이는 보통 실패. 지금은 고르지 마세요.
Modal / SSH / Daytona / Singularity → 각각 클라우드 샌드박스, 원격 머신, 클라우드 개발환경, HPC용입니다. 별도 계정·키·인프라가 있어야 의미가 있고, 지금 처음 세팅하는 단계엔 불필요.
결론. 그러니 그냥 Enter로 "Keep current (local)" 그대로 두면 된다.

2.8. Connect a messaging platform?

스킵해도 나중에 'hermes setup gateway' 명령어로 구성할 수 있기 때문에 스킵.
자세한 설정 방법은 다음 아래 포스팅 참고

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

Connect a messaging platform 이미지

2.9. Setup Complete! 

최초 환경 설정 끝! 다음편에서 도커 설정방법을 알아보자

Setup Complete! 이미지

정상 설치가 되었으니 AI 에이전트를 실행해보자

docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent

hermes ai agent 실행 이미지

 

다음 포스팅은 도커컴포즈를 작성하고 헤르메스를 실행할 차례.

2026.05.31 - [IT/AI 자동화] - 헤르메스(hermes agent) 도커 설치 방법! 2. 도커컴포즈 작성 (feat. 맥미니 + 클로드)