Docker로 Hermes Agent 실행하기

작성일:2026.06.17|수정일:2026.06.17|조회수:1

Agentic Codinghermes-agent-guide-series#hermes-agent#colima#docker
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 하나를 안정적으로 실행하는 것이다.

최종 구조는 단순하다.

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

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

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

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

1. Colima와 Docker CLI 준비

macOS에서 Docker Desktop을 쓰고 있다면 Colima 설치 부분은 건너뛰어도 된다. 여기서는 Docker Desktop 대신 Colima를 사용한다. 가볍고, CLI 중심으로 쓰기 편하고, Hermes처럼 백그라운드 프로세스를 하나 띄워두는 용도에는 충분하다.

먼저 Homebrew를 사용해 필요한 패키지를 설치한다.

SH
brew install colima docker docker-compose

가끔 Homebrew가 docker 바이너리를 설치해놓고 shell에서 바로 찾지 못하는 경우가 있다. 그럴 때는 링크를 확인한다.

SH
brew link docker || brew link --overwrite docker
rehash 2>/dev/null || true

Docker Compose는 Docker CLI 플러그인으로 동작한다. Homebrew로 설치한 Compose 플러그인을 Docker CLI가 찾지 못하면 docker compose version에서 실패할 수 있다. 그럴 때는 ~/.docker/config.json에 플러그인 경로를 추가한다.

SH
mkdir -p ~/.docker

python3 - <<'PY'
import json
import subprocess
from pathlib import Path

prefix = subprocess.check_output(["brew", "--prefix"], text=True).strip()
plugin_dir = f"{prefix}/lib/docker/cli-plugins"
path = Path.home() / ".docker" / "config.json"

data = {}
if path.exists() and path.read_text().strip():
    data = json.loads(path.read_text())

dirs = data.setdefault("cliPluginsExtraDirs", [])
if plugin_dir not in dirs:
    dirs.append(plugin_dir)

path.write_text(json.dumps(data, indent=2) + "\n")
print(f"configured: {plugin_dir}")
PY

설치가 제대로 됐는지 확인한다.

SH
colima version
docker --version
docker compose version

Colima를 시작하고, Docker CLI가 Colima context를 보게 한다.

SH
colima start --runtime docker --cpu 4 --memory 8 --disk 60
docker context use colima

마지막으로 Docker daemon에 연결되는지 확인한다. 에러 없이 빈 목록이 나오면 준비는 끝이다.

SH
docker ps

2. 상태 디렉터리 만들기

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

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

SH
mkdir -p ~/hermes-agents/personal
mkdir -p ~/hermes-agents/docker

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

SH
docker pull nousresearch/hermes-agent:latest
docker image ls nousresearch/hermes-agent

3. setup 실행하기

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

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

Nous Portal을 쓰고 싶다면 setup에 portal 옵션을 붙인다.

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

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

SH
ls -la ~/hermes-agents/personal

.env
config.yaml
sessions/
skills/
logs/

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

4. gateway 실행하기

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

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

실행 상태를 확인한다.

SH
docker ps
docker logs -f hermes-dev

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

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

SH
docker stop hermes-dev

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

SH
docker start hermes-dev

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

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

SH
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, 모델 이름, 네트워크를 먼저 봐야 한다.

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

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

6. Docker Compose로 정리하기

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

SH
cd ~/hermes-agents/docker

docker-compose.yml을 만든다.

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

실행한다.

SH
docker compose up -d

로그:

SH
docker compose logs -f hermes-dev

중지:

SH
docker compose down

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

SH
docker compose pull
docker compose up -d

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

마무리

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

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

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

댓글

댓글을 불러오는 중...