Hermes Agent Docker: 2026년 전체 배포 가이드

Two Docker Modes Explained — 시작하기 전에 선택하세요

대부분의 가이드는 이 결정을 완전히 건너뛰고 docker run으로 이동합니다. 하지 않다. 두 가지 모드는 보안 및 운영 프로필이 상당히 다릅니다.

Mode 1 — 컨테이너 내부에서 실행되는 헤르메스

Hermes와 그 모든 종속성은 이미지 안에 있습니다. 명명된 볼륨을 통해 상태를 관리합니다. 컨테이너 다시 시작 정책은 재부팅 후에도 컨테이너를 유지합니다. 이것이 가장 일반적인 생산 패턴입니다.

• 호스트로부터의 깔끔한 분리 - 실수로 컴퓨터에 쓰는 일이 없습니다.
• 완전한 이식성; 동일한 작성 파일을 사용하여 어디서나 재배포
• 기본적으로 실행하는 것보다 약간 높은 오버헤드

Mode 2 — 터미널 백엔드 샌드박스로서의 Docker

여기에서 Hermes는 호스트(또는 컨테이너)에서 직접 실행되며 Docker 데몬을 호출하여 셸 실행을 위해 임시 컨테이너를 가동합니다. Hermes가 데몬에 접근할 수 있도록 DOCKER_HOST을 설정하여 구성합니다.

export DOCKER_HOST=unix:///var/run/docker.sock # Linux export DOCKER_HOST=tcp://host.docker.internal:2375 # Windows/Mac (Docker Desktop)

전제 조건 및 환경 설정

이미지를 가져오기 전에 다음을 확인하세요.

• Docker Engine 24+ 또는 Docker Desktop 4.26+
• 준비된 LLM API 키: OpenAI(OPENAI_API_KEY), Anthropic(ANTHROPIC_API_KEY) 또는 로컬 Ollama 엔드포인트
• 포트 443의 아웃바운드 인터넷 액세스(LLM API 호출용)
• 적어도 2 GB RAM 컨테이너에 할당됨(Ollama 지원 설정에는 4GB 권장)

Windows-Specific Setup (Docker Desktop + WSL2)

Windows는 대부분의 Docker 배포가 조용히 중단되는 곳입니다. 다음을 주의하세요:

# Correct — Docker Desktop translates this automatically volumes: - hermes_data:/root/.hermes

DOCKER_HOST=npipe:////./pipe/docker_engine

[wsl2] memory=4GB processors=2

빠른 시작 — 5분 안에 Docker를 사용하여 Hermes Agent 실행

공식 이미지를 가져와서 설정 마법사를 실행하세요.

# Pull the latest image docker pull nousresearch/hermes-agent:latest # Run with a persistent volume for state docker run -it -v hermes_home:/root/.hermes -e OPENAI_API_KEY=your_key_here \ nousresearch/hermes-agent:latest

그만큼 설정 마법사 첫 실행에 시작됩니다. 다음을 수행하라는 메시지가 표시됩니다.

1. LLM 제공업체(OpenAI, Anthropic, Ollama 또는 사용자 정의 엔드포인트)를 선택하세요.
2. API 키 또는 엔드포인트 URL을 입력하세요.
3. 터미널 백엔드 구성(네이티브 또는 Docker 샌드박스)

완료되면 세션이 작동하는지 확인합니다.

> hello

Production Deployment with Docker Compose

베어 docker run 명령은 테스트용으로 작동합니다. 지속적인 것이 있으면 Compose를 사용하세요.

version: "3.9" services: hermes: image: nousresearch/hermes-agent:latest container_name: hermes-agent restart: unless-stopped stdin_open: true tty: true environment: # Use environment secrets — never hardcode keys in compose files OPENAI_API_KEY: ${OPENAI_API_KEY} ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} HERMES_LOG_LEVEL: info volumes: - hermes_home:/root/.hermes # Config + conversation history - hermes_skills:/root/.hermes/skills # Skill store — see next section deploy: resources: limits: memory: 2G cpus: "1.5" healthcheck: test: ["CMD", "hermes", "--health"] interval: 30s timeout: 10s retries: 3 start_period: 15s logging: driver: "json-file" options: max-size: "10m" max-file: "3" volumes: hermes_home: hermes_skills:

API 키를 .env 파일에 저장합니다(버전 제어에 적용되지 않음).

OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-...

컨테이너 재구축 전반에 걸쳐 Hermes 기술 보존

이것은 가장 간과되는 생산 문제입니다. 헤르메스는 학습한 스킬을 일반 설정과 별도로 저장합니다. 다음 경로를 명시적으로 마운트합니다.

이미지를 업데이트하는 경우:

docker compose pull docker compose up -d # Named volumes persist automatically

Advanced Topology — Host-Docker(형제 컨테이너) 설정

이 아키텍처는 Hermes가 격리된 코드 실행을 위해 형제 컨테이너를 조정하도록 하려는 경우에 사용됩니다(예: 사용자가 제출한 코드를 안전하게 실행).

┌─────────────────────────────────┐ │ Docker Host │ │ │ │ ┌──────────────┐ │ │ │ hermes-agent │◄──socket──────┤── /var/run/docker.sock │ │ container │ │ │ └──────┬───────┘ │ │ │ docker run (sibling) │ │ ┌──────▼───────┐ │ │ │ sandbox-1 │ (ephemeral) │ │ └──────────────┘ │ └─────────────────────────────────┘

이 토폴로지에 대한 구성을 작성합니다.

services: hermes: image: nousresearch/hermes-agent:latest restart: unless-stopped environment: OPENAI_API_KEY: ${OPENAI_API_KEY} DOCKER_HOST: unix:///var/run/docker.sock HERMES_TERMINAL_BACKEND: docker volumes: - hermes_home:/root/.hermes - /var/run/docker.sock:/var/run/docker.sock # Socket mount group_add: - "999" # docker group GID — adjust to match your host

Connecting Hermes to Claude via Telegram Bot

No 서면 가이드는 현재 이 내용을 다루고 있으며 비디오 형식으로만 표시됩니다. 전체 설정은 다음과 같습니다.

/newbot → Name: Hermes Agent → Username: your_hermes_bot → Save the token: 123456:ABC-DEF...

environment: ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} HERMES_LLM_PROVIDER: anthropic HERMES_TELEGRAM_TOKEN: ${TELEGRAM_BOT_TOKEN} HERMES_TELEGRAM_ALLOWED_USERS: "your_telegram_user_id"

docker compose up -d

다중 아키텍처 배포(ARM64 / Oracle 프리 티어 / Raspberry Pi)

nousresearch/hermes-agent 이미지는 멀티 아키텍처 매니페스트로 제공됩니다. ARM64가 지원됩니다. ARM 호스트에서 명시적으로 끌어옵니다.

# Oracle Free Tier (Ampere A1) or Raspberry Pi 4/5 docker pull --platform linux/arm64 nousresearch/hermes-agent:latest # Verify the architecture docker inspect nousresearch/hermes-agent:latest | grep Architecture

알려진 ARM 관련 문제:

• 일부 Ollama 모델 양자화(Q8)는 ARM에서 더 느리게 실행됩니다. 로컬 추론에는 Q4_K_M을 선호합니다.
• exec format error에 도달하면 --platform linux/arm64 플래그를 사용하고 있는지 확인하세요.
• Apple Silicon의 Docker Desktop은 기본적으로 ARM을 처리하므로 플랫폼 플래그가 필요하지 않습니다.

일반적인 Hermes Agent Docker 오류 문제 해결

발생할 가능성이 가장 높은 오류에 대한 참조 표는 다음과 같습니다.

Frequently Asked Questions

최종 생각: 체크리스트 및 다음 단계

학습 루프는 Hermes를 Docker에서 실행한 다른 모든 에이전트와 구분하는 요소입니다. 위의 설정은 실제로 루프를 보장합니다. 축적하다 — 재설정되지 않음 — 업데이트를 제공할 때마다.

프로덕션 준비 배포를 호출하기 전에 다음을 확인하세요.

• ☐ hermes_home 및 hermes_skills에 대해 생성된 명명된 볼륨
• ☐ Compose에 하드코딩되지 않은 .env에 저장된 API 키
• ☐ restart: unless-stopped 정책 활성화
• ☐ 상태 확인 통과: docker inspect hermes-agent --format='{{.State.Health.Status}}'
• ☐ 로그 순환 구성됨(max-size, max-file)
• ☐ 메모리 고갈을 방지하기 위해 설정된 리소스 제한
• ☐ 설정 마법사가 완료되고 첫 번째 채팅 세션이 확인되었습니다.
• ☐ (Mode 2인 경우) Docker 소켓 마운트가 확인되고 소켓 프록시가 고려됩니다.

즉시 가치를 얻기 위한 다음 단계:

1. 파일 요약, 코드 검토, 웹 조사 등 몇 가지 실제 작업을 실행하여 기술 라이브러리를 구축합니다.
2. 10~15개의 작업 후에 hermes skills list을 실행하여 학습된 내용을 확인하세요.
3. 맞춤형 기술 템플릿 및 메모리 튜닝을 다루는 에이전트 구성 문서는 Nous Research GitHub을 검토하세요.
4. Oracle 무료 등급을 사용 중인 경우 학습된 상태를 유지하면서 다운타임 없는 이미지 업데이트를 위해 cron 기반 docker compose pull && docker compose up -d을 설정하세요.