Hermes Agent는 Nous Research에서 만든 자가 학습 AI 에이전트로, Docker로 쉽게 설치하고 실행할 수 있습니다. 모든 데이터(설정, API 키, 세션, 스킬 등)는 호스트의 볼륨에 저장되어 업그레이드 시에도 안전합니다.
1. 전제 조건
Docker와 Docker Compose 설치
호스트에 데이터 디렉토리 준비: mkdir -p ~/.hermes
2. 초기 설정 (Setup Wizard)
처음 한 번만 실행합니다. API 키와 기본 설정을 안내해줍니다.
mkdir -p ~/.hermes
docker run -it –rm \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent setup
Windows에서는 다음과 같이 실행
docker run -it –rm -v “$HOME\.hermes:/opt/data” nousresearch/hermes-agent setup
LLM 제공자(Anthropic, OpenAI, OpenRouter 등) 선택
채팅 시스템(Telegram, Discord 등) 설정 추천
3. 기본 실행 방법
Gateway 모드 (추천 – 백그라운드, Telegram/Discord 등 연동)
docker run -d \
–name hermes \
–restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
nousresearch/hermes-agent gateway run
Dashboard(웹 UI) 함께 실행
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
Gateway: http://localhost:8642
Dashboard: http://localhost:9119
대화형 CLI (테스트용)
docker run -it –rm \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent
또는 –tui 옵션으로 현대적인 TUI 사용.
4. Docker Compose 추천 (편리함)
docker-compose.yml 예시:
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
ports:
– “8642:8642” # gateway API
– “9119:9119” # dashboard
volumes:
– D:\docker\hermes:/opt/data
environment:
– HERMES_DASHBOARD=1
# – ANTHROPIC_API_KEY=sk-… # .env 대신 직접 전달 가능
deploy:
resources:
limits:
memory: 4G
cpus: “2.0”
실행:
docker compose up -d
docker compose logs -f
5. 주요 명령어 및 사용법
업그레이드: docker pull nousresearch/hermes-agent:latest 후 컨테이너 재생성
로그 확인: docker logs -f hermes
내부 접속: docker exec -it hermes bash
다중 프로필: 하나의 컨테이너당 하나의 데이터 디렉토리 사용 (예: ~/.hermes-work, ~/.hermes-personal)
6. 보안 및 주의사항
포트 노출 시 API_SERVER_KEY 필수 설정하고, 필요 시 reverse proxy(Caddy, Nginx) 사용
Gateway와 Dashboard는 같은 컨테이너에서 실행하는 것이 안정적
Terminal backend로 Docker sandbox 사용 가능 (hermes config set terminal.backend docker)
여러 컨테이너가 같은 /opt/data를 동시에 쓰지 않도록 주의
Hermes Agent Docker 실행 시 Gateway + Dashboard 사용법 정리 (2026년 기준 최신)
1. 추천 Docker 실행 명령어 (Gateway + Dashboard 동시 실행)
docker run -d \
–name hermes \
–restart unless-stopped \
-v ~/.hermes:/opt/data \
-p 8642:8642 \ # Gateway API (OpenAI-compatible + 내부 API)
-p 9119:9119 \ # Web Dashboard
-e HERMES_DASHBOARD=1 \
nousresearch/hermes-agent gateway run
중요: Dashboard는 같은 컨테이너에서 Gateway와 함께 실행해야 정상 작동합니다. (별도 컨테이너 권장하지 않음)
2. 각 포트 역할
포트이름 용도 접근 URL 비고
8642 Gateway API OpenAI 호환 API, 내부 API, Bot 연동 http://localhost:8642 필수
9119 Web Dashboard 브라우저 관리 UI (설정, 세션, 로그 등) http://localhost:9119 옵션
3. Gateway (8642) 사용법
주요 기능:
Telegram, Discord, Slack 등 메시징 플랫폼 연결 (항상 실행 필요)
OpenAI-compatible API 제공 (/v1 엔드포인트) → Open WebUI, SillyTavern, Cursor 등 연동 가능
Agent 실행 및 Tool Gateway 관리
상태 확인:
curl http://localhost:8642/health
# 또는
docker logs -f hermes
설정:
처음 실행 시 hermes gateway setup (컨테이너 내부에서 실행)
API 키 보호: API_SERVER_KEY 환경변수 설정 강력 추천
4. Dashboard (9119) 사용법
브라우저에서 접속: http://localhost:9119
Dashboard에서 할 수 있는 주요 기능:
설정 관리 (모델, Provider, Config YAML 편집)
API 키 안전하게 관리
활성 세션 (Sessions) 모니터링 및 관리
Skills (자동 생성된 스킬) 확인/편집
Cron Jobs / Scheduled Automations 관리
Logs (Agent, Gateway, Error) 실시간 보기 + 필터
Analytics 및 사용량 통계
Gateway 상태 확인 (플랫폼 연결 상태)
Dashboard 옵션 (환경변수 또는 command로 제어):
–host 0.0.0.0 + –insecure: 외부에서 접근할 때 (보안 주의!)
Reverse Proxy (Nginx/Caddy) + HTTPS 추천
5. Docker Compose 추천 예시
YAML
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
ports:
– “8642:8642” # Gateway
– “9119:9119” # Dashboard
volumes:
– ~/.hermes:/opt/data
environment:
– HERMES_DASHBOARD=1
# – API_SERVER_KEY=your_strong_key_here # 보안 필수
# resources:
# limits:
# memory: 4G
6. 유용한 명령어 (컨테이너 내부)
# 컨테이너 들어가기
docker exec -it hermes bash
# 내부에서 실행
hermes gateway status
hermes gateway setup # 플랫폼 재설정
hermes doctor # 문제 진단
hermes logs # 로그 확인
업데이트 방법:
docker pull nousresearch/hermes-agent:latest
docker stop hermes && docker rm hermes
# 위 docker run 또는 compose up -d 다시 실행
Dashboard는 로컬 관리용으로 설계되었기 때문에, 외부 노출 시 반드시 인증(Reverse Proxy + Basic Auth 또는 Hermes의 API 키)과 방화벽을 함께 사용하세요.
======================================================================================================================
올바른 실행 방법 (권장)
Hermes Docker 이미지에서는 직접 /opt/hermes/hermes를 실행하면 Python 환경(venv)이 제대로 로드되지 않아 yaml 모듈 오류가 발생합니다.
Bash# 1. 컨테이너 접속
docker exec -it hermes bash
# 2. hermes CLI를 제대로 실행 (가장 중요!)
hermes gateway setup
또는 한 줄로:
Bashdocker exec -it hermes hermes gateway setup
왜 오류가 발생하나요?
/opt/hermes/hermes 스크립트는 venv를 활성화하지 않은 상태로 CLI를 호출합니다.
hermes 명령어는 Docker 이미지의 ENTRYPOINT / PATH에 등록된 래퍼로, venv + 모든 의존성(PyYAML 등)이 제대로 설정되어 있습니다.
추가 유용 명령어
목적명령어Gateway 초기 설정hermes gateway setupGateway 상태 확인hermes gateway status설정 재실행hermes gateway setup모델 설정hermes model 또는 hermes config전체 설정 마법사hermes setup로그 확인hermes logs도움말hermes –help
컨테이너 내부에서 자주 쓰는 명령어 모음
Bash# hermes 명령어가 제대로 되는지 확인
which hermes
hermes –version
# 설정 파일 위치 확인
ls -l ~/.hermes/ # 또는 /opt/data/
# config.yaml 직접 편집
nano ~/.hermes/config.yaml
그래도 오류가 발생한다면?
컨테이너 재시작 후 다시 시도Bashdocker restart hermes
docker exec -it hermes hermes gateway setup
최신 이미지로 풀하기Bashdocker pull nousresearch/hermes-agent:latest
docker stop hermes && docker rm hermes
# docker run … 다시 실행
Dashboard와 함께 실행 중이라면
Dashboard가 백그라운드로 실행되면서 충돌이 있을 수 있으니, HERMES_DASHBOARD=0으로 잠시 끄고 테스트해보세요.
Tip: 처음 설정할 때는 interactive 모드로 하는 것이 가장 편합니다.
Bash
docker exec -it hermes hermes gateway setup
===============================================================================================================