Mac에서 Docker로 Hermes Agent 설치하는 방법

Hermes Agent를 Mac에서 실행하는 방법은 여러 가지가 있습니다. 이 글은 그중에서도 Docker Desktop을 설치한 뒤 공식 Docker 이미지로 Hermes Agent를 실행하는 흐름에 집중합니다. 로컬 Python 환경을 직접 건드리지 않고 컨테이너 안에서 실행하고 싶을 때 적합한 방식입니다.

모델 연결은 API key를 직접 넣는 방식도 가능하지만, 이 글은 ChatGPT 계정으로 로그인하는 OpenAI Codex OAuth 흐름을 중심으로 설명합니다. 공식 Hermes Agent Docker 문서는 첫 실행에서 setup 명령으로 설정 마법사를 먼저 실행하는 흐름을 Quick start로 안내합니다. 그 다음 hermes model에서 OpenAI Codex provider를 선택해 ChatGPT OAuth를 설정하는 순서가 가장 덜 헷갈립니다.

준비물

Hermes Agent와 Docker 방식의 의미

Hermes Agent는 Nous Research가 공개한 AI agent 런타임입니다. 공식 문서 기준으로 로컬 설치, Docker 실행, Docker terminal backend 같은 여러 실행 방식이 있습니다. 여기서 다루는 방식은 “Hermes Agent 자체를 Docker 컨테이너 안에서 실행하는 방법”입니다.

Docker 방식의 장점은 실행 환경이 비교적 분리된다는 점입니다. Mac의 Python, Node.js, 브라우저 자동화 의존성을 직접 설치하지 않고 컨테이너 이미지 안에 포함된 환경을 사용할 수 있습니다. 대신 Docker Desktop이 먼저 실행되어 있어야 하고, 파일 접근은 사용자가 마운트한 폴더 범위 안에서 이해해야 합니다.

공식 Hermes Docker 문서는 컨테이너의 사용자 데이터 위치를 /opt/data로 설명합니다. 따라서 Mac의 ~/.hermes 폴더를 컨테이너의 /opt/data에 연결하는 것이 핵심입니다.

Mac에 Docker Desktop 설치하기

Docker 공식 문서는 Mac용 Docker Desktop을 Apple Silicon용과 Intel chip용으로 나누어 제공합니다. M1, M2, M3, M4 계열이라면 Apple Silicon용을 선택하고, 오래된 Intel Mac이라면 Intel chip용을 선택하면 됩니다.

설치 흐름은 간단합니다.

1. Docker 공식 Mac 설치 페이지에서 Mac 칩 종류에 맞는 Docker Desktop을 내려받는다.
2. Docker.dmg를 열고 Docker 앱을 Applications 폴더로 이동한다.
3. Applications 폴더에서 Docker Desktop을 실행한다.
4. 처음 실행 시 권한 요청과 약관 화면을 확인한다.
5. 메뉴 막대에 Docker 아이콘이 안정적으로 표시될 때까지 기다린다.

터미널에서 아래 명령으로 설치 여부를 확인합니다.

docker --version

정상 설치되어 있으면 Docker 버전이 출력됩니다. 명령을 찾을 수 없다는 메시지가 나오면 Docker Desktop이 아직 실행되지 않았거나 CLI 경로 설정이 끝나지 않았을 수 있습니다.

~/.hermes 볼륨 마운트가 필요한 이유

Docker 컨테이너는 기본적으로 지웠다 다시 만들 수 있는 실행 환경입니다. 따라서 설정, OAuth 토큰, 세션, 로그, skills 같은 데이터를 컨테이너 안에만 두면 업데이트나 재실행 때 잃어버리기 쉽습니다.

Hermes Agent 공식 Docker 문서는 /opt/data를 사용자 데이터의 중심 위치로 설명합니다. Mac의 ~/.hermes 폴더를 /opt/data에 연결하면 컨테이너를 다시 만들어도 중요한 데이터가 Mac 쪽에 남습니다.

첫 실행: Hermes setup wizard 실행하기

Docker Desktop과 볼륨 위치를 확인했다면, 공식 Docker 문서의 Quick start처럼 먼저 설정 마법사를 실행합니다. 이 단계는 Hermes Agent를 “설치”한다기보다, 앞으로 계속 재사용할 데이터 폴더를 초기화하고 기본 설정을 만드는 과정에 가깝습니다.

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

이 명령을 실행하면 일회성 컨테이너가 열리고, 컨테이너 안의 /opt/data가 Mac의 ~/.hermes와 연결됩니다. --rm 때문에 컨테이너 자체는 종료 후 사라지지만, 설정 파일과 인증 정보는 ~/.hermes에 남습니다.

setup wizard에서 실제로 진행되는 일

공식 Docker 문서 기준으로 Hermes Agent 이미지는 첫 실행 때 /opt/data 볼륨을 부트스트랩합니다. 따라서 setup wizard를 한 번 통과하면 다음과 같은 파일과 폴더가 준비됩니다.

setup wizard가 묻는 항목은 Hermes Agent 버전에 따라 조금씩 달라질 수 있습니다. 다만 초보자는 아래 기준으로 진행하면 이해하기 쉽습니다.

즉, 이 글의 추천 흐름은 setup으로 기본 파일과 폴더를 만든 뒤, provider 선택이 애매하면 hermes model로 모델 설정을 다시 여는 방식입니다. setup 화면에서 바로 OpenAI Codex와 ChatGPT OAuth를 선택할 수 있다면 그대로 진행해도 됩니다.

setup 직후 확인하기

setup wizard가 끝나면 터미널에서 아래처럼 데이터 폴더가 만들어졌는지 확인합니다.

ls -la ~/.hermes

config.yaml이 생겼는지도 확인합니다. 파일 전체를 공개하거나 공유하지 말고, 로컬에서 일부만 보는 정도가 안전합니다.

sed -n '1,80p' ~/.hermes/config.yaml

.env에는 secret이 들어갈 수 있으므로 내용을 화면에 그대로 출력하지 않는 편이 좋습니다. 존재 여부만 확인하려면 다음처럼 파일 목록만 봅니다.

ls -la ~/.hermes/.env

setup이 끝났는데 ~/.hermes/config.yaml이 없거나 폴더가 비어 있다면, 대부분은 볼륨 마운트가 잘못된 경우입니다. 이때는 명령에 -v ~/.hermes:/opt/data가 빠지지 않았는지 먼저 확인합니다.

만약 setup wizard에서 provider를 건너뛰었거나 나중에 모델을 바꾸고 싶다면, 다음 섹션의 hermes model 명령으로 다시 설정할 수 있습니다. 중요한 점은 이후 모든 명령에서 같은 -v ~/.hermes:/opt/data 볼륨을 계속 쓰는 것입니다.

ChatGPT OAuth로 모델 provider 설정하기

Hermes Agent는 여러 모델 provider를 지원합니다. 이 글에서는 API key를 직접 저장하는 대신, ChatGPT OAuth를 사용하는 OpenAI Codex provider를 설정합니다. 공식 Hermes Agent 문서에서는 hermes model을 실행해 provider와 모델을 대화형으로 고를 수 있다고 설명합니다.

setup wizard에서 모델 설정을 끝내지 않았거나 다시 확인하고 싶다면 아래 명령을 실행합니다.

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

화면에 provider 선택 메뉴가 나오면 OpenAI Codex 또는 Codex로 표시되는 항목을 선택합니다. 이후 Hermes Agent가 브라우저 로그인 URL이나 device code를 안내하면, Mac의 브라우저에서 해당 URL을 열고 ChatGPT 계정으로 로그인합니다.

문서나 버전에 따라 credential pool 명령을 직접 사용할 수도 있습니다.

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

이 OAuth 토큰은 컨테이너 안에만 남는 것이 아니라, 마운트된 ~/.hermes 데이터 폴더 아래의 인증 저장소에 보관됩니다. 그래서 컨테이너를 지웠다가 다시 만들어도 같은 데이터 폴더를 연결하면 설정을 이어서 사용할 수 있습니다.

Docker로 Hermes Agent 실행하기

setup wizard와 OAuth 설정이 끝났다면 같은 ~/.hermes 폴더를 마운트해 Hermes Agent를 실행합니다.

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

이 명령의 의미는 다음과 같습니다.

대화형 실행이 정상적으로 열리면 기본 설치와 provider 연결이 된 것입니다. 그 다음에야 필요에 따라 gateway 모드나 dashboard 같은 상시 실행 구성을 추가하는 편이 안전합니다.

설치 확인하기

setup wizard, provider 설정, 대화형 실행까지 끝났다면 아래 명령으로 설치 상태를 다시 확인합니다.

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

OAuth provider가 설정되었는지 확인하려면 같은 데이터 폴더를 연결한 상태에서 인증 목록이나 설정 화면을 확인합니다.

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

컨테이너를 백그라운드 gateway 모드로 실행하고 dashboard까지 확인하려면 다음처럼 이름, 재시작 정책, 포트, dashboard 환경 변수를 함께 지정합니다. 공식 Docker 문서 기준으로 gateway는 8642, dashboard는 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

이 상태에서 Mac 브라우저로 http://localhost:9119에 접속하면 Hermes dashboard가 접속되어야 합니다. 같은 로컬 주소인 http://127.0.0.1:9119로도 확인할 수 있습니다. 이 dashboard는 설정, 세션, 로그, skills 등을 브라우저에서 확인하기 위한 로컬 관리 화면입니다.

브라우저가 바로 열리지 않거나 빈 화면이 보이면 먼저 HTTP 응답이 오는지 확인합니다.

curl -I http://127.0.0.1:9119

로그 확인은 다음 명령을 사용합니다. dashboard가 함께 실행되면 로그에 [dashboard]로 시작하는 줄이 섞여 나올 수 있습니다.

docker logs --tail 50 hermes

중지와 삭제는 다음과 같습니다.

docker stop hermes
docker rm hermes

자주 생기는 문제 해결

Apple Silicon Mac에서 Intel용 이미지를 강제로 쓰는 상황이 아니라면 보통 Docker Desktop이 아키텍처 차이를 처리합니다. 다만 특정 이미지나 의존성이 x86 전용일 때는 속도나 호환성 문제가 생길 수 있으므로, 먼저 공식 이미지의 latest 태그와 Docker Desktop 최신 버전을 사용하는 것이 좋습니다.

업데이트와 삭제 방법

Hermes Agent Docker 이미지를 업데이트하려면 새 이미지를 받은 뒤 컨테이너를 다시 만들면 됩니다. ~/.hermes 폴더를 유지하면 OAuth 인증, 설정, 세션은 그대로 남습니다.

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
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

완전히 삭제하려면 컨테이너와 이미지뿐 아니라 데이터 폴더까지 지워야 합니다. 단, ~/.hermes를 삭제하면 인증 토큰, 설정, 세션, 로그가 함께 사라집니다.

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

데이터까지 지울 때만 다음 명령을 사용합니다.

rm -rf ~/.hermes

핵심 정리

Mac에서 Docker로 Hermes Agent를 실행할 때 핵심은 세 가지입니다. 먼저 Docker Desktop이 정상적으로 실행되어야 합니다. 다음으로 ChatGPT OAuth를 통해 OpenAI Codex provider를 설정합니다. 마지막으로 ~/.hermes:/opt/data 볼륨 마운트를 통해 OAuth 토큰, 설정, 세션을 컨테이너 밖에 보존해야 합니다.

처음에는 model 또는 setup 명령으로 provider 설정을 끝내고, 이후 필요하면 gateway run으로 백그라운드 실행을 구성하는 흐름이 가장 이해하기 쉽습니다.

주요 출처

• Hermes Agent 공식 Docker 문서
• Hermes Agent Web Dashboard 문서
• Hermes Agent AI Providers 문서
• Hermes Agent Credential Pools 문서
• Hermes Agent 공식 설치 문서
• NousResearch Hermes Agent GitHub 설치 문서
• Docker Desktop Mac 설치 문서
• Docker Desktop Mac 권한 문서
• Docker Hub nousresearch/hermes-agent 이미지