Docker

기준일: 2026-07-26
공식 기준: Docker

Docker 문서는 Hermes Agent 공식 문서(user-guide/docker)를 한국어로 정리한 가이드입니다. Running Hermes Agent in Docker and using Docker as a terminal backend 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Running Hermes Agent in Docker and using Docker as a terminal backend

한국어 가이드 범위: user-guide/docker 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Hermes Agent — Docker
• 빠른 시작
• Running in gateway mode
• Running the dashboard
• Running interactively (CLI chat)
• Persistent volumes
• Immutable install tree
• Multi-profile support
• Create a profile — registers the gateway- s6 slot.
• Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart.
• Status — reports Manager: s6 (container supervisor) inside the container.
• Remove a profile — tears down the s6 slot too.
• Reaching more than one profile from outside the container
• Create the profile (registers its gateway- s6 slot)
• Point its API server at a free port (write to the profile's own .env)
• Why one container with many profiles, not many containers
• When you DO want a separate container
• Where the logs go
• Environment variable forwarding
• Docker Compose example
• Optional: Linux desktop audio bridge
• Resource limits
• What the Dockerfile does
• docker exec automatically drops to the hermes user
• Per-profile gateway supervision
• Upgrading
• Skills and credential files
• Installing more tools in the container
• npm or Python tools — use npx or uvx
• Other tools (apt packages, binaries) — install and remember
• Durable installs — build a derived image
• Complex tools or multi-service stacks — run a sidecar container
• Broadly useful tools — open an issue or pull request
• Connecting to local inference servers (vLLM, Ollama, etc.)
• Docker Compose (recommended)
• Standalone Docker run (no Compose)
• config.yaml
• config.yaml
• Verifying connectivity
• Ollama

상세 내용

Hermes Agent — Docker

There are two distinct ways Docker intersects with Hermes Agent:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

빠른 시작

If this is your first time running Hermes Agent, create a data directory on the host and start the container interactively to run the setup wizard:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

Running in gateway mode

Once configured, run the container in the background as a persistent gateway (Telegram, Discord, Slack, WhatsApp, etc.):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

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="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

Running the dashboard

The built-in web dashboard runs as a supervised s6-rc service alongside the gateway in the same container. Set HERMES_DASHBOARD=1 to bring it up:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Username/password — the simplest for a self-hosted / on-prem / homelab container on a trusted network or behind a VPN: set HERMES_DASHBOARD_BASIC_AUTH_USERNAME + HERMES_DASHBOARD_BASIC_AUTH_PASSWORD (and HERMES_DASHBOARD_BASIC_AUTH_SECRET for restart-stable sessions). Not suitable for direct public-internet exposure.
• OAuth (Nous Portal) — for hosted/public deploys: the dashboard_auth/nous provider activates whenever HERMES_DASHBOARD_OAUTH_CLIENT_ID is set.
• Self-hosted OIDC — to authenticate against your own identity provider via standard OpenID Connect: the dashboard_auth/self_hosted provider activates when HERMES_DASHBOARD_OIDC_ISSUER + HERMES_DASHBOARD_OIDC_CLIENT_ID are set.

Environment variable	Description	Default
HERMES_DASHBOARD	Set to 1 (or true / yes) to enable the supervised dashboard service	(unset — service is registered but stays down)
HERMES_DASHBOARD_HOST	Bind address for the dashboard HTTP server	0.0.0.0
HERMES_DASHBOARD_PORT	Port for the dashboard HTTP server	9119
HERMES_DASHBOARD_INSECURE	Deprecated / no-op. Formerly bypassed the auth gate; as of the June 2026 hardening it no longer disables authentication. A non-loopback bind always requires an auth provider	(ignored — configure a provider instead)

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

Running interactively (CLI chat)

To open an interactive chat session against a running data directory:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

/opt/hermes/.venv/bin/hermes

Persistent volumes

The /opt/data volume is the single source of truth for all Hermes state. It maps to your host's ~/.hermes/ directory and contains:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Path	Contents
.env	API keys and secrets
config.yaml	All Hermes configuration
SOUL.md	Agent personality/identity
sessions/	Conversation history
memories/	Persistent memory store
skills/	Installed skills
home/	Per-profile HOME for Hermes tool subprocesses (git, ssh, gh, npm, and skill CLIs)
cron/	Scheduled job definitions
hooks/	Event hooks
logs/	Runtime logs
skins/	Custom CLI skins

Immutable install tree

In hosted and published Docker images, /opt/hermes is the installed application tree. It is root-owned and read-only to the runtime hermes user, so agent turns, gateway sessions, dashboard actions, and normal docker exec hermes hermes ... commands cannot edit the core source, bundled .venv, node_modules, or TUI bundle in place.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Multi-profile support

Hermes supports multiple profiles — separate ~/.hermes/ subdirectories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. Inside the official Docker image, the s6 supervision tree treats each profile as a first-class supervised service, so the recommended deployment is one container hosting all profiles.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• A dedicated s6 service slot at /run/service/gateway-<name>/, registered dynamically by the runtime — no container rebuild required.
• Auto-restart on crash, backoff-managed by s6-supervise.
• Per-profile rotated logs at ${HERMES_HOME}/logs/gateways/<name>/current (10 archives × 1 MB each).
• State persistence across container restarts: the boot-time reconciler reads gateway_state.json from each profile directory and brings the slot back up only for profiles whose last recorded state was running. Only a gateway you explicitly stopped (hermes gateway stop) stays down across a restart — a container restart, image upgrade, or unexpected exit leaves the recorded state as running, so the gateway auto-starts on the next boot.

Create a profile — registers the gateway- s6 slot.

docker exec hermes hermes profile create coder

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart.

docker exec hermes hermes -p coder gateway start docker exec hermes hermes -p coder gateway stop docker exec hermes hermes -p coder gateway restart

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Status — reports Manager: s6 (container supervisor) inside the container.

docker exec hermes hermes -p coder gateway status

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Remove a profile — tears down the s6 slot too.

docker exec hermes hermes profile delete coder ```

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Reaching more than one profile from outside the container

Two different surfaces reach a profile's gateway from outside, and they behave differently — don't conflate them:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Create the profile (registers its gateway- s6 slot)

docker exec hermes hermes profile create work

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Point its API server at a free port (write to the profile's own .env)

cat >> /opt/data/profiles/work/.env <<'EOF' API_SERVER_ENABLED=true API_SERVER_PORT=8643 EOF

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Why one container with many profiles, not many containers

Before the s6 migration, "one container per profile" was the recommended pattern because there was no in-container supervisor to manage multiple gateways. With s6 as PID 1, that's no longer necessary, and the single-container layout is simpler in almost every dimension:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

	One container, many profiles	One container per profile
Disk overhead	One image, one bundled venv, one Playwright cache	N images / N caches
Memory overhead	Shared Python interpreter cache, shared node_modules	Duplicated per container
Profile creation	docker exec ... hermes profile create <name> (seconds)	New docker run invocation + port allocation + bind-mount config
Per-profile crash recovery	s6-supervise auto-restart	Docker's --restart unless-stopped (slower, kills sibling work)
Logs	Per-profile rotated file via s6-log, plus container-boot audit log	docker logs <name> per container — no built-in rotation
Backup	One ~/.hermes directory	N directories to coordinate

When you DO want a separate container

Profile-in-container is the default. Run a separate container per profile only when you have a specific reason:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Resource isolation per workload — e.g. a runaway browser-tool session in profile A shouldn't be able to OOM profile B. Containers give you --memory / --cpus per profile.
• Independent image pinning — different upstream image tags per workload.
• Network segmentation — distinct Docker networks per profile (e.g. one customer-facing, one internal).
• Compliance / blast radius — distinct credentials never share an OS-level process tree.
• "8642:8642"
• ~/.hermes-work:/opt/data
• "8643:8642"
• ~/.hermes-personal:/opt/data

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

Where the logs go

The s6 container has four distinct log surfaces, and "why isn't my gateway showing anything in docker logs" is a common surprise. Cheatsheet:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• The file copy at logs/gateways/<profile>/current is what survives container restarts. docker logs only retains output from the current container's lifetime (and is wiped on docker rm); the rotated files persist on the bind-mounted volume.
• The boot reconciler's audit line shape is <iso-timestamp> profile=<name> prior_state=<state> action=<registered|started>, so a quick grep profile=coder ~/.hermes/logs/container-boot.log reveals when a given profile was last restored and whether s6 auto-started it.

Source	Where it lands	How to read it
Per-profile gateway (hermes gateway run and per-profile gateways under s6)	Tee'd to two places: docker logs <container> (real time, no extra prefix) and ${HERMES_HOME}/logs/gateways/<profile>/current (rotated, ISO-8601 timestamped, 10 archives × 1 MB each)	docker logs -f hermes or tail -F ~/.hermes/logs/gateways/default/current on the host
Dashboard (when HERMES_DASHBOARD=1)	docker logs <container> (no prefix)	docker logs -f hermes — interleaved with gateway lines
Boot reconciler (records which profile gateways were restored on each container start)	${HERMES_HOME}/logs/container-boot.log (append-only audit log)	tail -F ~/.hermes/logs/container-boot.log
Generic Hermes logs (agent.log, errors.log)	${HERMES_HOME}/logs/ (profile-aware)	docker exec hermes hermes logs --follow [--level WARNING] [--session <id>]

Environment variable forwarding

API keys are read from /opt/data/.env inside the container. You can also pass environment variables directly:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

Docker Compose example

For persistent deployment with both the gateway and dashboard, a docker-compose.yaml is convenient:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "8642:8642" # gateway API
• "9119:9119" # dashboard (only reached when HERMES_DASHBOARD=1)
• ~/.hermes:/opt/data
• HERMES_DASHBOARD=1

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: 4G
          cpus: "2.0"

Optional: Linux desktop audio bridge

Voice mode in Docker needs two separate things to work: Hermes must be allowed to probe audio devices inside the container, and the container must be able to reach your host audio server. The setup below covers the host audio plumbing for Linux desktops that expose a PulseAudio-compatible socket, including many PipeWire setups.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• ~/.hermes:/opt/data
• /run/user/${HERMES_UID}/pulse:/run/user/${HERMES_UID}/pulse
• ~/.config/pulse/cookie:/tmp/pulse-cookie:ro
• ./asound.conf:/etc/asound.conf:ro
• HERMES_UID=${HERMES_UID}
• HERMES_GID=${HERMES_GID}
• XDG_RUNTIME_DIR=/run/user/${HERMES_UID}
• PULSE_SERVER=unix:/run/user/${HERMES_UID}/pulse/native
• PULSE_COOKIE=/tmp/pulse-cookie

Then build a small derived image with the ALSA PulseAudio plugin installed:

Use that image in Compose and pass through the host user's PulseAudio socket and cookie:

Start it with your host UID/GID so the container process can access the per-user audio socket:

To verify what PortAudio sees inside the container:

Resource limits

The Hermes container needs moderate resources. Recommended minimums:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Resource	Minimum	Recommended
Memory	1 GB	2–4 GB
CPU	1 core	2 cores
Disk (data volume)	500 MB	2+ GB (grows with sessions/skills)

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

What the Dockerfile does

The official image is based on debian:13.4 and includes:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Python 3.13 with dependencies synced from the lockfile via uv sync --frozen --no-install-project for the baked extras (all, messaging, Anthropic/Bedrock/Azure identity, Hindsight, Matrix), followed by a no-dependency editable install of Hermes itself.
• Node.js 22 + npm (for browser automation, WhatsApp bridge, TUI/Desktop bundles, and workspace build tooling)
• Playwright with Chromium (npx playwright install --with-deps chromium --only-shell)
• ripgrep, ffmpeg, git, and xz-utils as system utilities
• docker-cli — so agents running inside the container can drive the host's Docker daemon (bind-mount /var/run/docker.sock to opt in) for docker build, docker run, container inspection, etc.
• openssh-client — enables the SSH terminal backend from inside the container. The SSH backend shells out to the system ssh binary; without this, it failed silently in containerized installs.
• The WhatsApp bridge (scripts/whatsapp-bridge/)
• s6-overlay v3 as PID 1 (replaces the older tini) — supervises the dashboard and per-profile gateways with auto-restart on crash, reaps zombie subprocesses, and forwards signals.
• no args → hermes (the default)
• first arg is an executable on PATH (e.g. sleep, bash) → exec it directly
• anything else → hermes <args> (subcommand passthrough)

docker exec automatically drops to the hermes user

docker exec hermes defaults to running as root inside the container, but the image ships a thin shim at /opt/hermes/bin/hermes (earliest on PATH) that detects root callers and transparently re-execs through s6-setuidgid hermes. So docker exec hermes login, docker exec hermes profile create …, docker exec hermes setup, etc. all write files owned by UID 10000 — i.e. readable by the supervised gateway — with no extra --user flag needed. Non-root callers (the supervised processes themselves, docker exec --user hermes, kanban subagents inside the container) hit a short-circuit that exec's the venv binary directly, so there's no overhead on the hot paths.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

docker exec -e HERMES_DOCKER_EXEC_AS_ROOT=1 hermes <cmd>

Per-profile gateway supervision

Each profile created with hermes profile create automatically gets an s6-supervised gateway service registered at /run/service/gateway-/, with state-persistent auto-restart across container restarts. See Multi-profile support above for the user-facing workflow and the lifecycle commands.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Gateway crashes are auto-restarted by s6-supervise after a ~1s backoff.
• Dashboard, when enabled with HERMES_DASHBOARD=1, is supervised on the same supervision tree and gets the same auto-restart treatment.
• docker restart, image upgrades (docker compose up -d --force-recreate), and unexpected exits preserve running gateways: the cont-init reconciler reads $HERMES_HOME/profiles/<name>/gateway_state.json and brings the slot back up if the last recorded state was running. Only an explicit hermes gateway stop records stopped and keeps the gateway down across the restart; the container/s6 SIGTERM sent on a restart or upgrade is treated as "still running" and auto-starts.
• Per-profile gateway logs persist under $HERMES_HOME/logs/gateways/<profile>/current (rotated by s6-log), and the reconciler's actions are appended to $HERMES_HOME/logs/container-boot.log per boot. See Where the logs go for the full routing map.

Upgrading

Pull the latest image and recreate the container. Your data directory is preserved, and the container runs non-interactive config-schema migrations against the mounted $HERMES_HOME/config.yaml before starting the gateway. When a migration is needed, Hermes writes timestamped backups next to config.yaml and .env first.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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 compose pull
docker compose up -d

Skills and credential files

When using Docker as the execution environment (not the methods above, but when the agent runs commands inside a Docker sandbox — see Configuration → Docker Backend), Hermes reuses a single long-lived container for all tool calls and automatically bind-mounts the skills directory (~/.hermes/skills/) and any credential files declared by skills into that container as read-only volumes. Skill scripts, templates, and references are available inside the sandbox without manual configuration, and because the container persists for the life of the Hermes process, any dependencies you install or files you write stay around for the next tool call.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Installing more tools in the container

The official image ships with a curated set of utilities (see What the Dockerfile does), but not every tool an agent might want is preinstalled. There are five recommended approaches, in increasing order of effort and durability.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

npm or Python tools — use npx or uvx

For any tool published to npm or PyPI, instruct Hermes to run it via npx (npm) or uvx (Python) and to remember that command in its persistent memory. If the tool needs a config file or credentials, instruct it to drop those under /opt/data (e.g. /opt/data//config.yaml).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Other tools (apt packages, binaries) — install and remember

For anything outside npm or PyPI — apt packages, prebuilt binaries, language runtimes not already in the image — instruct Hermes how to install it (e.g. apt-get update && apt-get install -y ) and tell it to remember the install command. The tool persists for the rest of the container's lifetime, and Hermes will re-run the install command after a container restart when it next needs the tool.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Durable installs — build a derived image

When a tool must be available immediately on every container start with no re-install delay, build a new image that inherits from nousresearch/hermes-agent and installs the tool in a layer:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

FROM nousresearch/hermes-agent:latest

USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends <your-package> \
    && rm -rf /var/lib/apt/lists/*
USER hermes

docker build -t my-hermes:latest .
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  my-hermes:latest gateway run

Complex tools or multi-service stacks — run a sidecar container

For tools that bring their own service (a database, a web server, a queue, a headless browser farm) or that are too heavy to live inside the Hermes container, run them as a separate container on a shared Docker network. Hermes reaches the sidecar by container name, the same way it reaches a local inference server (see Connecting to local inference servers).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "8642:8642"
• ~/.hermes:/opt/data
• hermes-net
• hermes-net

services:
  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

  my-tool:
    image: example/my-tool:latest
    container_name: my-tool
    restart: unless-stopped
    networks:
      - hermes-net

networks:
  hermes-net:
    driver: bridge

Broadly useful tools — open an issue or pull request

If a tool is likely to be useful to most Hermes Agent users, consider contributing it upstream rather than carrying it in a private derived image. Open an issue or pull request on the hermes-agent repository describing the tool and its use case. Tools that get bundled into the official image benefit every user and avoid the maintenance overhead of a downstream fork.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Connecting to local inference servers (vLLM, Ollama, etc.)

When running Hermes in Docker and your inference server (vLLM, Ollama, text-generation-inference, etc.) is also running on the host or in another container, networking requires extra attention.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Docker Compose (recommended)

Put both services on the same Docker network. This is the most reliable approach:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• "8000:8000"
• hermes-net
• capabilities: [gpu]
• "8642:8642"
• ~/.hermes:/opt/data
• hermes-net
• Use the container name (vllm) as the hostname — not localhost or 127.0.0.1, which refer to the Hermes container itself.
• The model value must match the --served-model-name you passed to vLLM.
• Set api_key to any non-empty string (vLLM requires the header but doesn't validate it by default).
• Do not include a trailing slash in base_url.

services:
  vllm:
    image: vllm/vllm-openai:latest
    container_name: vllm
    command: >
      --model Qwen/Qwen2.5-7B-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

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

Standalone Docker run (no Compose)

If your inference server runs directly on the host (not in Docker), use host.docker.internal on macOS/Windows, or --network host on Linux:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

config.yaml

model: provider: custom model: my-model base_url: http://host.docker.internal:8000/v1 api_key: "none" sh docker run -d \

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

**Linux (host networking):**

config.yaml

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

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Verifying connectivity

From inside the Hermes container, confirm the inference server is reachable:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

Ollama

Ollama works the same way. If Ollama runs on the host, use host.docker.internal:11434 (macOS/Windows) or 127.0.0.1:11434 (Linux with --network host). If Ollama runs in its own container on the same Docker network:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

Container exits immediately

Check logs: docker logs hermes. Common causes:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Missing or invalid .env file — run interactively first to complete setup
• Port conflicts if running with exposed ports

"Permission denied" errors

The container's stage2 hook drops privileges to the non-root hermes user (UID 10000) via s6-setuidgid inside each supervised service. If your host ~/.hermes/ is owned by a different UID, set HERMES_UID/HERMES_GID — or their PUID/PGID aliases, for parity with LinuxServer.io and NAS images — to match your host user, or ensure the data directory is writable:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

chmod -R 755 ~/.hermes

docker run -d \
  --name hermes \
  -e PUID=1000 -e PGID=10 \
  -v /volume1/docker/hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Browser tools not working

Playwright needs shared memory. Add --shm-size=1g to your Docker run command:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

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

Gateway not reconnecting after network issues

The --restart unless-stopped flag handles most transient failures. If the gateway is stuck, restart the container:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

docker restart hermes

Checking container health

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

실습 체크리스트

1. 공식 문서와 설치된 Hermes 버전을 대조합니다.
2. 관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
3. Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
4. 시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

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

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

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

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="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

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

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

/opt/hermes/.venv/bin/hermes

# Create a profile — registers the gateway-<name> s6 slot.
docker exec hermes hermes profile create coder

# Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart.
docker exec hermes hermes -p coder gateway start
docker exec hermes hermes -p coder gateway stop
docker exec hermes hermes -p coder gateway restart

# Status — reports `Manager: s6 (container supervisor)` inside the container.
docker exec hermes hermes -p coder gateway status

# Remove a profile — tears down the s6 slot too.
docker exec hermes hermes profile delete coder

관련 링크

• 공식 원문: user-guide/docker
• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.