Docker

anchor alias

헤르메스 에이전트 — Docker

Docker는 Hermes Agent에서 두 가지 방식으로 사용할 수 있습니다.

1. Hermes를 Docker 안에서 실행 - 에이전트 자체가 컨테이너 내부에서 실행됩니다. 이 페이지의 주된 범위입니다.
2. Docker를 터미널 백엔드로 사용 - 에이전트는 호스트에서 실행하고, 명령 실행만 하나의 지속적인 Docker 샌드박스 컨테이너 안에서 처리합니다. 이 컨테이너는 Hermes 프로세스가 살아 있는 동안 도구 호출, /new, 서브에이전트 사이에서 유지됩니다. 자세한 내용은 Configuration → Docker Backend를 보세요.

이 페이지는 1번 방식을 다룹니다. 컨테이너는 호스트에서 /opt/data로 마운트한 단일 디렉터리에 모든 사용자 데이터(config, API 키, 세션, 스킬, 메모리)를 저장합니다. 이미지 자체는 stateless이므로 설정을 잃지 않고 새 버전을 pull해 업그레이드할 수 있습니다.

빠른 시작

Hermes Agent를 실행하는 첫 번째 시간이라면 호스트에 데이터 디렉토리를 생성하고 설정 마법사를 실행하기 위해 컨테이너를 대화로 시작합니다.

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

이 설정 마법사로 당신을 떨어 뜨리고 API 키에 대해 프롬프트하고 ~/.hermes/.env로 작성합니다. 한 번만 할 필요가 있습니다. 이 시점에서 작업할 게이트웨이의 채팅 시스템을 설정하는 것이 좋습니다.

Gateway 모드에서 실행

일단 구성되면, persistent Gateway (Telegram, Discord, Slack, WhatsApp 등)로 배경에 컨테이너를 실행하세요

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

포트 8642 게이트웨이의 OpenAI-compatible API 서버 및 건강 엔드포인트를 노출합니다. 채팅 플랫폼 (Telegram, Discord, etc.)만 사용한다면 선택적이지만, 게이트웨이에 도달하기 위해 대시보드 또는 외부 도구를 원하는 경우 필요합니다.

참고: API 서버는 API_SERVER_ENABLED=true에 게이트됩니다. 컨테이너 내부의 127.0.0.1 이상을 노출하려면 API_SERVER_HOST=0.0.0.0와 API_SERVER_KEY (최소 8 자 — openssl rand -hex 32로 하나 생성)를 설정합니다. 예:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY=your_api_key_here \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

인터넷에 어떤 포트를 열면 보안 위험이 있습니다. 위험을 이해하지 않으면 안됩니다.

대시보드 실행

내장 웹 대시보드는 게이트웨이와 같은 컨테이너 내부의 옵션 측면 처리로 실행됩니다. HERMES_DASHBOARD=1 을 설정하고 포트 9119 를 표시하고 게이트웨이의 8642 를 표시하세요

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 dashboard을 배경으로 시작합니다. hermes 사용자로 실행됩니다. 대시보드 출력은 [dashboard]과 docker logs로 설정되어 게이트웨이 로그에서 분리할 수 있습니다.

환경변수	설명	기본 정보
HERMES_DASHBOARD	1 (또는 true / yes)로 설정하여 메인 명령과 대시보드를 실행합니다	(unset — 대시보드가 시작되지 않음)
HERMES_DASHBOARD_HOST	대쉬보드 HTTP 서버의 Bind 주소	0.0.0.0
HERMES_DASHBOARD_PORT	대쉬보드 HTTP 서버 포트	9119
HERMES_DASHBOARD_TUI	1로 설정하여 브라우저 채팅 탭 (PTY/WebSocket을 통해 hermes --tui로 설정)	(설정)

기본적으로 HERMES_DASHBOARD_HOST=0.0.0.0는 게시된 포트를 통해 대시보드에 도달하기 위해 필요한 것입니다. 입력점은 --insecure를 hermes dashboard로 자동으로 전달합니다. 127.0.0.1 에 대한 대시보드를 in-container access only(e.g. back the reverse proxy in the sidecar)에 제한하려면.

노트

대쉬보드 사이드 프로세스는 가 supervised이 아닙니다. 충돌하면 컨테이너 재시작까지 유지됩니다. 별도의 컨테이너로 실행하면 지원되지 않습니다. 대쉬보드의 Gateway-liveness detection는 Gateway 프로세스와 공유된 PID 네임스페이스가 필요합니다.

대화식으로 실행 (CLI 채팅)

실행 데이터 디렉토리에 대한 대화 세션을 엽니다

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

또는 이미 실행 컨테이너의 터미널을 열 경우 (예를 들어 Docker Desktop을 통해), 그냥 실행:

/opt/hermes/.venv/bin/hermes

지속적인 양

/opt/data 볼륨은 모든 Hermes 상태에 대한 진실의 단일 소스입니다. 그것은 호스트의 ~/.hermes/ 디렉토리에 맵을 포함:

오시는길	설명
.env	API 키와 비밀
config.yaml	모든 Hermes 구성
SOUL.md	에이전트 성격/identity
sessions/	회사연혁
memories/	영구 기억 상점
skills/	설치 기술
cron/	시간표 작업 정의
hooks/	이벤트 훅
logs/	Runtime 로그
skins/	사용자 정의 CLI 스킨

경고

두 개의 헤르메스 게이트웨이 동시에 동일한 데이터 디렉토리에 대한 컨테이너를 실행하지 마십시오 - 세션 파일 및 메모리 상점은 동시 쓰기 액세스를 위해 설계되지 않습니다.

Multi-profile 지원

Hermes는 다중 프로필을 지원하며, 단일 설치에서 서로 독립적인 에이전트(SOUL, 스킬, 메모리, 세션, 자격 증명)를 실행할 수 있도록 ~/.hermes/ 디렉터리를 분리합니다. Docker에서 실행할 때는 Hermes의 내장 멀티 프로필 기능을 사용하는 것을 권장하지 않습니다.

대신, 권장 패턴은 프로필당 하나의 컨테이너, 각 컨테이너 바인딩 - /opt/data로 자체 호스트 디렉토리를 마운트:

# Work profile
docker run -d \
  --name hermes-work \
  --restart unless-stopped \
  -v ~/.hermes-work:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

# Personal profile
docker run -d \
  --name hermes-personal \
  --restart unless-stopped \
  -v ~/.hermes-personal:/opt/data \
  -p 8643:8642 \
  nousresearch/hermes-agent gateway run

왜 Docker에 있는 단면도에 분리되는 콘테이너:

• Isolation - 각 컨테이너에는 자체 파일 시스템, 프로세스 테이블 및 리소스 제한이 있습니다. 충돌, 종속 변화, 또는 한 프로파일에 런웨이 세션은 다른 영향을 미치지 않습니다.
• 독립적 인 라이프 사이클 - 업그레이드, 재시작, 일시 중지, 또는 각 에이전트를 다시 롤 (docker restart hermes-work 잎 hermes-personal untouched).
• 클린 포트 및 네트워크 분리 - 각 게이트웨이는 자체 호스트 포트를 바인딩합니다. 채팅 플랫폼 또는 API 서버간에 크로스 토크의 위험이 없습니다.
• 간단한 정신 모델 - 컨테이너 *is * 프로필. 백업, 마이그레이션 및 권한 모두 바인드 마운트 디렉토리를 따르고, 추가 --profile 플래그가 기억되지 않습니다.
• Avoids concurrent-write risk - 같은 데이터 디렉토리에 대한 두 개의 게이트웨이를 결코 실행하지 않고 여전히 단일 컨테이너 내에서 프로파일에 적용.

Docker Compose에서, 이것은 단지 명백한 container_name, volumes, 그리고 ports를 가진 단면도 당 1개의 서비스를 선언하는 것을 의미합니다:

services:
  hermes-work:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-work
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes-work:/opt/data

  hermes-personal:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-personal
    restart: unless-stopped
    command: gateway run
    ports:
      - "8643:8642"
    volumes:
      - ~/.hermes-personal:/opt/data

환경 변수 운송

API 키는 컨테이너 내부의 /opt/data/.env에서 읽습니다. 환경 변수를 직접 전달할 수 있습니다:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent
``-e` 플래그는 `.env`의 값을 무시합니다. 이것은 당신이 디스크에 열쇠를 원하지 않는 곳에 CI/CD 또는 비밀 관리 통합을 위해 유용합니다.

## Docker 컴파일 예제 \{#docker-compose-example}

게이트웨이와 대시보드 모두의 지속적인 배포를 위해 `docker-compose.yaml`는 편리합니다

```yaml
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"   # gateway API
      - "9119:9119"   # dashboard (only reached when HERMES_DASHBOARD=1)
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      # Uncomment to forward specific env vars instead of using.env file:
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
      # - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 
          cpus: "2.0"
``docker compose up -d`로 시작하고 `docker compose logs -f`로 로그인하세요. 대시보드 출력은 `[dashboard]`로 미리 설정되어 게이트웨이 로그에서 필터링하기 쉽습니다.

## 자원 제한 \{#docker-compose-example}

Hermes 컨테이너는 온건한 리소스를 필요로 합니다. 추천된 최소한:

| 회사연혁 | 지원하다 | (주) |
|----------|---------|-------------|
| 기억하기 | 1 GB | 2–4 GB |
| CPU의 | 1개의 핵심 | 2개의 핵심 |
| Disk (데이터 볼륨) | 500 MB | 2+ GB ( 세션/스킬로그램) |

Browser Automation (Playwright/Chromium)은 가장 기억이 드는 기능입니다. 브라우저 도구를 필요로하지 않으면 1 GB가 충분합니다. 브라우저 도구가 활성화되어 최소 2 GB를 할당합니다.

Docker의 제한 설정:

```sh
docker run -d \
  --name hermes \
  --restart unless-stopped \
  --memory=4g --cpus=2 \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Dockerfile은 무엇입니까

공식 이미지는 debian:13.4에 근거하여 다음을 포함합니다:

• 모든 헤르메스 의존성 파이썬 3 (uv pip install -e ".[all]")
• Node.js + npm (브라우저 자동화 및 WhatsApp 브리지용)
• 크롬과 장난 (npx playwright install --with-deps chromium --only-shell)
• ripgrep, ffmpeg, git 및 시스템 유틸리티로 tini
• docker-cli — 컨테이너 내부에서 실행하는 에이전트는 호스트의 Docker daemon (bind-mount __HMES_TOKEN_00001__에서 선택) docker build, docker run, 컨테이너 검사 등을 구동할 수 있습니다.
• openssh-client — 컨테이너 내부에서 SSH 터미널 백엔드를 활성화합니다. 시스템 ssh 바이너리에 SSH 백엔드 쉘을 넣으십시오. 이없이, 그것은 컨테이너 설치에서 조용히 실패했습니다.
• WhatsApp 브리지 (scripts/whatsapp-bridge/)

Entrypoint 스크립트 (docker/entrypoint.sh)는 첫 번째 실행에 데이터 볼륨을 부팅합니다

• 디렉토리 구조 생성 (sessions/, memories/, skills/ 등)
• Copies .env.example → .env if no .env 존재
• Copies 기본 config.yaml 누락된 경우
• Copies 기본 SOUL.md 누락된 경우
• Syncs Bundled Skills using the appear-based method (사용자 편집을 예약)
• 옵션 출시 hermes dashboard는 HERMES_DASHBOARD=1 (대시 대시보드를 볼 수 있음)
• 그런 다음 hermes을 실행합니다

경고

명령 체인에서 /opt/hermes/docker/entrypoint.sh을 유지하지 않는 이미지 엔트리포인트를 무시하지 마십시오. 엔트리 포인트는 hermes 사용자에 루트 권한이 생성됩니다. hermes gateway run 를 시작으로 공식 이미지 안에 루트가 /opt/data에 뿌리가 있는 파일들을 남겨주고, 나중에 대쉬보드나 게이트웨이가 시작되기 때문에 기본적으로 거부됩니다. HERMES_ALLOW_ROOT_GATEWAY=1 를 설정하면 의도적으로 그 위험을 수용합니다.

업그레이딩

최신 이미지를 잡아 컨테이너를 다시 만듭니다. 사용자의 데이터 디렉토리가 untouched.

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

또는 Docker 컴파일:

docker compose pull
docker compose up -d

기술 및 자격 파일

실행 환경으로 Docker를 사용할 때 (위의 메소드가 아니라 Docker sandbox 내부 명령을 실행할 때 - Configuration → Docker Backend를 참조하세요. Hermes는 모든 도구 호출에 대한 단일 긴 수명 컨테이너를 재사용하고 자동으로 기술 디렉토리 (~/.hermes/skills/) 및 읽기 전용 볼륨으로 그 컨테이너에 의해 스킬에 의해 선언 된 모든 자격 증명 파일. Skill scripts, Templates, references are available inside the sandbox without manual configuration, and because the container pers for the life of the Hermes process, 당신이 설치 또는 파일에 대해 쓰기 다음 도구 호출.

동일한 동기화는 SSH 및 Modal 백엔드에 대해 발생합니다. - 기술 및 자격 파일은 각 명령의 앞에 rsync 또는 Modal 마운트 API를 통해 업로드됩니다.

로컬 inference 서버에 연결 (vLLM, Ollama 등)

Docker에서 헤르메스를 실행할 때 (vLLM, Ollama, text-generation-inference 등)는 호스트 또는 다른 컨테이너에서 실행되며 네트워킹은 추가주의를 요구합니다.

Docker Compose (추천)

같은 Docker 네트워크에 두 서비스를 넣어. 이것은 가장 신뢰할 수있는 접근법입니다

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    command: >
      --model Qwen/Qwen2.5--Instruct
      --served-model-name my-model
      --host 0.0.0.0
      --port 8000
    ports:
      - "8000:8000"
    networks:
      - hermes-net
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data
    networks:
      - hermes-net

networks:
  hermes-net:
    driver: bridge

그런 다음 ~/.hermes/config.yaml에서 컨테이너 이름를 호스트 이름으로 사용합니다

model:
  provider: custom
  model: my-model
  base_url: http://vllm:8000/v1
  api_key: "none"

Key points

• 컨테이너 이름 (vllm) 를 호스트 이름으로 사용하세요. - localhost 또는 127.0.0.1는 Hermes 컨테이너 자체를 나타냅니다.
• model 값은 vLLM에 전달된 --served-model-name와 일치해야 합니다.
• api_key 를 비empty string(vLLM은 헤더가 필요하지만 기본적으로 유효하지 않습니다)로 설정합니다.
• **는 base_url의 트레일 슬래시가 포함되어 있지 않습니다.

독립 도커 런 (Comperose)

inference 서버가 호스트에 직접 실행되는 경우 ( Docker에서 아닙니다), OS / Windows에서 host.docker.internal, 또는 Linux에서 --network host를 사용하세요

** macOS / 윈도우:**

docker run -d \
  --name hermes \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run
````yaml
# config.yaml
model:
  provider: custom
  model: my-model
  base_url: http://host.docker.internal:8000/v1
  api_key: "none"

Linux (호스트 네트워킹):

docker run -d \
  --name hermes \
  --network host \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run
````yaml
# config.yaml
model:
  provider: custom
  model: my-model
  base_url: http://127.0.0.1:8000/v1
  api_key: "none"

With --network host, the -p flag is ignored — all container ports are directly exposed on the host.

연결하기

헤르메스 컨테이너 내부에서, inference 서버가 도달 할 수 확인:

docker exec hermes curl -s http://vllm:8000/v1/models

JSON 응답은 제공된 모델을 나열해야 합니다. 이 실패한 경우, 체크:

1. 컨테이너 모두 같은 Docker 네트워크에 있습니다 (docker network inspect hermes-net)
2. inference 서버는 0.0.0.0, not 127.0.0.1에 대해 듣고 있습니다
3. 포트 번호 일치

오라마

Ollama는 같은 방법을 사용합니다. Ollama가 호스트에서 실행되면 host.docker.internal:11434 (macOS/Windows) 또는 127.0.0.1:11434 (--network host와 리눅스)를 사용하세요. Ollama가 같은 Docker 네트워크에 자체 컨테이너에서 실행하면:

model:
  provider: custom
  model: llama3
  base_url: http://ollama:11434/v1
  api_key: "none"

문제 해결

컨테이너 출구 즉시

로그 확인: docker logs hermes입니다. 일반적인 원인:

• Missing or invalid .env 파일 - 처음 실행하여 설정 완료
• 노출된 항구로 달리면 포트 충돌

"출입 거부" 오류

컨테이너의 엔트리 포인트는 hermes 사용자 (UID 10000)에 비 루트 gosu에 특권을 부여합니다. 호스트의 경우 ~/.hermes/는 다른 UID에 의해 소유, 설정 HERMES_UID/HERMES_GID 호스트 사용자에 맞게, 또는 데이터 디렉토리는 writable:

chmod -R 755 ~/.hermes

브라우저 도구 작동하지 않음

Playwright는 공유 메모리가 필요합니다. --shm-size=1g를 Docker 실행 명령에 추가하세요

docker run -d \
  --name hermes \
  --shm-size=1g \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

네트워크 문제 후 다시 연결하지 Gateway

--restart unless-stopped 플래그는 가장 일시적인 실패를 처리합니다. 게이트웨이가 붙어 있다면, 컨테이너를 재시작:

docker restart hermes

컨테이너의 건강

docker logs --tail 50 hermes          # Recent logs
docker run -it --rm nousresearch/hermes-agent:latest version     # Verify version
docker stats hermes                    # Resource usage