Docker로 Hermes Agent 실행하기

Hermes Agent를 터미널에서 한 번 실행해보는 것은 어렵지 않다. 설치하고, 모델을 고르고, hermes를 실행하면 된다. 문제는 그 다음이다. Discord나 Telegram에서 계속 부르고 싶다면 Hermes는 터미널을 닫아도 살아 있어야 한다. 설정과 메모리와 스킬도 남아 있어야 한다. 나중에 서버로 옮기거나 컨테이너를 다시 만들 때도 “내 Hermes”가 그대로 따라와야 한다.

그래서 나는 Hermes Agent를 Docker로 띄우는 편이 좋다고 본다. Docker를 쓰면 실행 환경을 비교적 깔끔하게 고정할 수 있고, 상태 디렉터리만 잘 보존하면 컨테이너는 언제든 다시 만들 수 있다.

이 글에서는 macOS에서 Colima와 Docker CLI를 준비하고, nousresearch/hermes-agent:latest 이미지를 사용해 Hermes Agent를 하나 띄우는 데까지 간다. 목표는 거창한 멀티 에이전트 시스템이 아니다. 먼저 개인용 Hermes 하나를 안정적으로 실행하는 것이다.

최종 구조는 단순하다.

~/hermes-agents/  personal/   # Hermes 상태: config, env, sessions, skills, memory  docker/     # Docker Compose 파일과 운영 스크립트

personal은 Hermes의 실제 상태가 쌓이는 곳이다. 컨테이너 안에서는 이 디렉터리를 /opt/data로 mount한다.

host directory                 ->  container directory~/hermes-agents/personal       ->  /opt/data

docker는 에이전트들이 협업하는 공간이 아니다. Docker Compose 파일처럼 컨테이너를 어떻게 띄울지 적어두는 운영 파일 위치다.

1. 상태 디렉터리 만들기

Hermes를 Docker로 띄울 때 가장 중요한 것은 컨테이너가 아니라 상태 디렉터리다. 컨테이너는 지워도 다시 만들 수 있다. 이미지는 다시 받을 수 있다. 하지만 config.yaml, .env, sessions, skills, memory가 들어 있는 상태 디렉터리를 잃으면 내가 키운 Hermes의 맥락이 사라진다.

먼저 디렉터리를 만든다. personal은 Hermes 하나의 집이다. 나중에 coding, research, blog 같은 에이전트를 더 만들더라도, 지금은 personal 하나만 제대로 띄우는 데 집중한다.

mkdir -p ~/hermes-agents/personalmkdir -p ~/hermes-agents/docker

이제 이미지를 받고 확인한다.

docker pull nousresearch/hermes-agent:latestdocker image ls nousresearch/hermes-agent

2. setup 실행하기

처음 설정은 컨테이너를 일회성으로 실행해서 진행한다. 중요한 점은 ~/hermes-agents/personal을 컨테이너의 /opt/data로 mount하는 것이다.

docker run -it --rm \  -v ~/hermes-agents/personal:/opt/data \  nousresearch/hermes-agent:latest setup

설정이 끝나면 호스트의 ~/hermes-agents/personal 아래에 대략 이런 파일들이 생긴다.

ls -la ~/hermes-agents/personal.envconfig.yamlsessions/skills/logs/

.env에는 API key나 bot token 같은 비밀값이 들어간다. 절대 Git에 올리면 안 된다.

3. gateway 실행하기

Discord나 Telegram에서 Hermes를 부르려면 gateway가 계속 살아 있어야 한다. 이제 같은 상태 디렉터리를 mount해서 gateway를 실행한다.

docker run -d \  --name hermes-personal \  --restart unless-stopped \  -v ~/hermes-agents/personal:/opt/data \  nousresearch/hermes-agent:latest gateway run

실행 상태를 확인한다.

docker psdocker logs -f hermes-personal

문제가 없으면 gateway가 시작되고, 설정한 플랫폼이 있다면 해당 platform adapter가 올라오는 로그가 보인다.

컨테이너를 잠깐 멈추고 싶다면 지우지 말고 stop을 쓴다.

docker stop hermes-personal

다시 켤 때는 start를 쓴다. 이 방식은 기존 컨테이너를 그대로 살려서 다시 실행한다. 설정, 로그, 컨테이너 이름도 유지된다.

docker start hermes-personal

4. CLI query로 모델 설정 확인하기

Gateway만 보면 문제가 어디 있는지 헷갈릴 수 있다. Discord에서 대답이 안 올 때 그게 Discord 설정 문제인지, 모델 provider 문제인지, API key 문제인지 바로 알기 어렵다. 그래서 같은 상태 디렉터리를 mount한 뒤 CLI query를 한 번 실행해본다.

docker run -it --rm \  -v ~/hermes-agents/personal:/opt/data \  nousresearch/hermes-agent:latest chat -q "짧게 pong이라고 답해줘"

여기서 응답이 나오면 모델 provider와 기본 Hermes 설정은 정상이다. Discord나 Telegram에서만 안 된다면 gateway/platform 설정 문제로 좁혀볼 수 있다. 반대로 이 명령부터 실패한다면 bot token을 보기 전에 provider 설정, API key, 모델 이름, 네트워크를 먼저 봐야 한다.

docker run -it --rm \  -v ~/hermes-agents/personal:/opt/data \  nousresearch/hermes-agent:latest doctor

doctor는 의존성이나 설정 문제를 빠르게 보는 데 유용하다.

5. Docker Compose로 정리하기

docker run 명령이 길어지기 시작하면 Docker Compose로 옮기는 편이 낫다. 실행 방법이 파일로 남아야 나중에 다시 띄우기 쉽다.

cd ~/hermes-agents/docker

docker-compose.yml을 만든다.

services:  hermes-personal:    image: nousresearch/hermes-agent:latest    container_name: hermes-personal    restart: unless-stopped    volumes:      - ../personal:/opt/data    command: gateway run

실행한다.

docker compose up -d

로그:

docker compose logs -f hermes-personal

중지:

docker compose down

이미지를 업데이트하고 다시 띄우고 싶다면:

docker compose pulldocker compose up -d

여기서도 중요한 점은 같다. Docker Compose 파일은 컨테이너를 관리할 뿐이고, 진짜 상태는 ../personal에 있다.

마무리

Docker로 Hermes Agent를 띄우는 핵심은 명령어 자체가 아니다. 상태 디렉터리를 먼저 정하고, 그 디렉터리를 컨테이너의 /opt/data로 mount하는 것이다.

이미지는 언제든 다시 받을 수 있다. 컨테이너도 다시 만들 수 있다. 하지만 ~/hermes-agents/personal에 쌓인 설정, 세션, 스킬, 메모리는 그렇지 않다.

처음에는 personal 하나면 충분하다. 이 하나가 안정적으로 돌아가고 나면 그때 coding, research, blog 같은 에이전트를 나누면 된다. 순서는 단순하다. 먼저 하나를 살려두고, 그 다음에 나눈다.