Hermes Agent는 Nous Research가 공개한 오픈소스 에이전트입니다. 대화만 하는 챗봇과 달리 터미널 명령을 실행하고 파일을 읽고 쓰는 도구를 갖고 있어서, 설치한 컴퓨터에서 할 수 있는 일을 에이전트가 대신 할 수 있습니다. 이 글에서는 그 점을 고려해, 호스트 PC가 아니라 일회용 Docker 컨테이너 안에 설치하는 과정까지 다룹니다. 설치 스크립트 실행, 첫 실행 화면, hermes doctor 점검, ~/.hermes 데이터 폴더, 웹 대시보드 로그인을 직접 확인합니다.
이 글은 Hermes Agent 실무 시리즈의 1편입니다. 이어지는 글에서 로컬 모델 연결, 명령 승인, MCP, 메모리와 스킬을 같은 컨테이너에서 차례로 다룹니다.
- 1편 이 글: 컨테이너에 설치하고 첫 실행하기
- 2편 로컬 Ollama 모델을 Hermes Agent에 연결하기
- 3편 Hermes Agent의 명령 승인 절차 확인하기
- 4편 Hermes Agent에 MCP filesystem 서버를 붙이고 접근 범위 제한하기
- 5편 Hermes Agent의 스킬과 메모리, 저장되는 정보 확인하기
왜 호스트가 아니라 컨테이너인가
공식 보안 문서에 따르면 터미널 백엔드의 기본값은 local이고, 이 경우 격리가 없어서 에이전트가 실행하는 명령이 호스트에서 그대로 실행됩니다. 위험한 명령에는 승인 절차가 붙지만, 승인은 명령 정책이지 운영체제 수준의 샌드박스가 아니라고 문서가 직접 밝히고 있습니다. 모델이 잘못된 명령을 내거나 프롬프트 인젝션에 속았을 때 피해가 어디까지 번지는지는 에이전트가 실행되는 환경이 정합니다.
설치 방식도 이유 가운데 하나입니다. 공식 설치는 curl ... | bash로 내려받은 스크립트를 바로 실행하는 형태이고, 파이썬과 Node.js 실행 환경을 ~/.hermes 아래에 통째로 내려받습니다. 이런 설치는 지울 수 있는 환경에서 먼저 해 보는 편이 안전합니다. 컨테이너와 볼륨을 지우면 설치와 에이전트가 남긴 흔적이 모두 사라집니다.
이 시리즈의 약속은 세 가지입니다. 에이전트는 컨테이너 안에서만 실행하고, 일반 사용자(agent)로 실행하며, 연습용 폴더(practice)에서만 파일을 만지게 합니다.
준비물
| 항목 | 확인한 버전 |
|---|---|
| Docker Desktop 또는 Docker Engine | 29.5.3 |
| Docker Compose | docker compose 명령 (Docker 29에 포함) |
| 기본 이미지 | ubuntu:24.04 (24.04.5 LTS) |
| Hermes Agent | v0.22.5 (2026.9.24), stable |
| 브라우저 | Chrome (대시보드 확인용) |
| 디스크 여유 | 약 7GB (이미지 약 4GB, 데이터 볼륨 약 2.3GB) |
명령은 Git Bash 기준입니다. 설치 스크립트가 내려받는 양이 많아서 이미지를 만드는 데 5분 안팎이 걸렸습니다. 이 글은 외부 API 키를 쓰지 않습니다.
1. 작업 폴더와 Dockerfile 만들기
mkdir hermes-lab && cd hermes-lab
Dockerfile을 만듭니다. 설치 스크립트가 필요로 하는 curl, git, tar와 인증서를 먼저 깔고, 일반 사용자 agent를 만든 뒤 그 사용자로 설치 스크립트를 실행합니다. --non-interactive는 입력이 필요한 단계를 건너뛰는 옵션이고, --skip-browser와 --skip-computer-use는 이 실습에서 쓰지 않는 브라우저 도구와 화면 제어 도구를 받지 않는 옵션입니다. tmux는 이후 글에서 TUI 화면을 파일로 남길 때 쓰며, 직접 실행해 보는 데에는 필요하지 않습니다.
FROM ubuntu:24.04
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
&& apt-get install -y --no-install-recommends curl git ca-certificates tar xz-utils sudo less procps tmux \
&& rm -rf /var/lib/apt/lists/*
# 에이전트는 일반 사용자로 실행합니다.
RUN useradd -m -s /bin/bash agent \
&& echo "agent ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/agent
USER agent
WORKDIR /home/agent
ENV PATH="/home/agent/.local/bin:${PATH}"
# 브라우저 도구는 이 실습에서 쓰지 않으므로 건너뜁니다.
RUN curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-browser --skip-computer-use
# 연습용 폴더입니다. 컨테이너 안에서 에이전트가 만지는 파일은 여기에만 둡니다.
RUN mkdir -p /home/agent/practice
CMD ["bash"]
docker-compose.yml을 만듭니다. 데이터 폴더(~/.hermes)와 연습용 폴더(practice)를 이름 있는 볼륨에 두어서, 컨테이너를 다시 만들어도 설정과 기록이 남게 합니다. extra_hosts는 2편에서 호스트의 Ollama에 접속할 때 쓰는 host.docker.internal 이름을 만들어 줍니다. 대시보드용 환경 변수와 포트는 7단계에서 설명합니다. 포트를 127.0.0.1에만 연 것은 대시보드가 내 PC 밖으로 노출되지 않게 하려는 것입니다.
services:
hermes:
build: .
image: cr-hermes:lab
container_name: cr-hermes-lab
tty: true
stdin_open: true
working_dir: /home/agent
volumes:
- hermes-data:/home/agent/.hermes
- hermes-practice:/home/agent/practice
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
HERMES_DASHBOARD_BASIC_AUTH_USERNAME: admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: lab-only-pass
HERMES_DASHBOARD_BASIC_AUTH_SECRET: lab-only-secret-0123456789abcdef
ports:
- "127.0.0.1:5500:9119"
volumes:
hermes-data:
hermes-practice:
2. 이미지 만들기
docker compose build
설치 스크립트의 출력이 길게 이어지고, 마지막은 다음처럼 끝납니다.
# 기대 출력 (끝부분, 체크 표시는 [통과]로 적었습니다)
[통과] Install complete! [detached @ bf0203a794]
[통과] added ~/.local/bin to PATH in /home/agent/.bashrc
[통과] Hermes Agent install complete. Run: hermes
Image cr-hermes:lab Built
설치 스크립트는 소스를 ~/.hermes/hermes-agent에 내려받고, 고정된 버전의 Python 3.14, Node.js, npm, ripgrep, FFmpeg를 ~/.hermes/tools에 따로 받습니다. 시스템 Python을 쓰지 않으므로 컨테이너에 Python을 따로 깔 필요가 없습니다. 이 과정에서 에이전트가 쓸 번들 스킬 58개가 함께 복사됩니다.
3. 컨테이너를 띄우고 버전 확인하기
docker compose up -d
docker compose ps
docker compose exec hermes hermes --version
docker compose exec hermes id
# 기대 출력
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
cr-hermes-lab cr-hermes:lab "bash" hermes 19 seconds ago Up 6 seconds 127.0.0.1:5500->9119/tcp
Hermes Agent v0.22.5 (2026.9.24) · stable · local bf0203a794a0
Install directory: /home/agent/.hermes/hermes-agent
Install method: git
Python: 3.14.9
OpenAI SDK: 2.24.0
Up to date
uid=1001(agent) gid=1001(agent) groups=1001(agent)

PORTS 열이 127.0.0.1:5500->9119로 나오면 포트가 내 PC에서만 열린 것입니다. 마지막 줄이 uid=0(root)가 아니라 agent인지도 꼭 확인합니다.
4. hermes doctor로 점검하기
docker compose exec hermes hermes doctor
hermes doctor는 필요한 구성 요소가 빠졌는지 확인하고 해결 방법을 알려 주는 점검 명령입니다. 이 글의 환경에서는 필수 항목이 모두 통과했고, 선택 항목만 경고로 표시되었습니다.
# 기대 출력 (앞부분, 화면의 체크 표시는 [통과], 경고 표시는 [경고]로 적었습니다)
◆ Python Environment
[통과] Python 3.14.9
[통과] SQLite 3.53.1
◆ Required Packages
[통과] OpenAI SDK
[통과] Rich (terminal UI)
[경고] python-telegram-bot (optional, not installed)
[경고] discord.py (optional, not installed)
[통과] Dashboard web surface (imports cleanly)
◆ Configuration Files
[통과] ~/.hermes/.env file exists
[통과] ~/.hermes/config.yaml exists
◆ Auth Providers
[경고] Nous Portal auth (not logged in)
[경고] OpenAI Codex auth (not logged in)

끝부분에는 Found 4 issue(s) to address가 나왔습니다. API 키가 아직 없다는 안내 한 건과, 번들된 npm 패키지에 알려진 취약점이 있다는 안내 세 건(루트, web, ui-tui)이었습니다. 취약점 안내는 업스트림 lockfile이 고쳐지기를 기다리라는 내용이고, Docker에서는 다시 빌드한 이미지를 받으라는 안내가 붙습니다. 이번 환경에서 고칠 수 있는 항목이 아니므로 그대로 두었습니다. 모델 연결은 2편에서 합니다.
5. 데이터 폴더 구조 보기
docker compose exec hermes bash -c 'ls -pA ~/.hermes; echo; du -sh ~/.hermes; ls ~/.local/bin'
# 기대 출력
.env
.hermes-update-in-progress.lock
SOUL.md
audio_cache/
auth.lock
backups/
cache/
config.yaml
cron/
hermes-agent/
hooks/
image_cache/
installs/
logs/
memories/
pairing/
sessions/
skills/
source-checks/
telemetry/
tools/
2.3G /home/agent/.hermes
hermes
hermes-acp
hermes-agent

~/.hermes는 설정과 기록뿐 아니라 설치 자체(hermes-agent, installs, tools)도 담고 있어서 2.3GB나 됩니다. 문서에서 안내하는 핵심 파일과 폴더는 다음과 같습니다.
| 이름 | 용도 |
|---|---|
config.yaml |
모델, 터미널 백엔드, 승인 방식 같은 설정 |
.env |
API 키 같은 비밀값 |
SOUL.md |
에이전트의 기본 성격 설명 |
memories/ |
에이전트가 기억하는 내용 (5편) |
skills/ |
번들 스킬과 에이전트가 만든 스킬 (5편) |
sessions/, logs/ |
대화 기록과 로그 |
config.yaml은 이 환경에서 2,000줄이 넘습니다. 대부분 주석으로 된 설명이며, 값은 hermes config get 키로 읽고 hermes config set 키 값으로 바꾸는 편이 안전합니다.
6. 첫 실행 화면 보기
연습용 폴더에서 hermes를 실행합니다.
docker compose exec -w /home/agent/practice hermes hermes
처음 실행하면 사용 통계 공유 여부를 묻는 질문이 먼저 나옵니다. 공유하면 활동량과 오류 종류 같은 집계 값을 Nous에 하루에 한 번 보낸다는 설명이 붙어 있고, 이 글에서는 No thanks를 골랐습니다. 나중에 hermes setup telemetry로 바꿀 수 있습니다.

그 뒤 도구 20개와 스킬 54개가 있다는 시작 화면이 나오고, 모델이 아직 없으므로 공급자를 설정하겠느냐고 묻습니다. 기본값으로 표시된 모델 이름(claude-opus-4.6)은 아직 연결된 것이 아니라 기본 표시일 뿐입니다. n을 누르면 입력 화면이 열리지만 모델이 없으므로, 여기서는 /exit를 입력해 나옵니다.

이 캡처에서는 위쪽의 큰 로고와 도구 목록을 줄였습니다. hermes doctor가 설정 파일을 통과로 표시해도 모델은 비어 있으므로, 이 질문이 나오는 것이 정상입니다.
7. 웹 대시보드 열어 보기
Hermes에는 설정, 세션, 스킬, MCP, 로그를 브라우저에서 다루는 대시보드가 있습니다. 문서에 따르면 127.0.0.1이 아닌 주소에 열면 인증이 필수이며, 인증 설정이 없으면 시작하지 않습니다. 그래서 docker-compose.yml에 사용자 이름과 비밀번호를 환경 변수로 넣었습니다. 값은 이 실습용 예시이므로, 다른 환경에서는 반드시 바꿔 쓰십시오.
docker compose exec -d hermes bash -lc 'hermes dashboard --host 0.0.0.0 --no-open > /tmp/dash.log 2>&1'
docker compose exec hermes tail -3 /tmp/dash.log
# 기대 출력
HERMES_DASHBOARD_READY port=9119
Hermes Web UI → http://0.0.0.0:9119
처음 시작할 때는 화면 파일을 준비하느라 1분가량 걸렸습니다. 준비되면 브라우저에서 http://localhost:5500을 열고 admin과 lab-only-pass로 로그인합니다.

로그인 뒤 왼쪽 메뉴에서 Models를 열면 현재 기본 모델이 anthropic/claude-opus-4.6(auto)으로 보입니다. 6단계에서 본 것과 같은, 아직 아무것도 연결하지 않은 기본값입니다. 2편에서 모델을 연결한 뒤 이 화면이 어떻게 바뀌는지 다시 봅니다.

자주 막히는 곳
| 증상 | 원인과 해결 |
|---|---|
hermes: command not found |
설치 스크립트는 ~/.local/bin을 .bashrc에 추가합니다. 로그인하지 않는 셸에서는 PATH에 안 잡힐 수 있어서 Dockerfile에서 ENV PATH를 직접 지정했습니다 |
| 이미지를 다시 빌드했는데 설치된 버전이 그대로입니다 | 이름 있는 볼륨은 처음 만들 때만 이미지의 ~/.hermes 내용으로 채워집니다. 설치본을 새로 받으려면 docker compose down -v로 볼륨을 지우고 다시 올립니다. 설정도 함께 지워집니다 |
| 대시보드가 시작하지 않습니다 | 0.0.0.0처럼 로컬이 아닌 주소에 열 때는 인증 설정이 필요하다고 문서가 안내합니다. docker compose exec hermes env로 HERMES_DASHBOARD_BASIC_AUTH_* 값이 컨테이너 안에 있는지 확인합니다 |
| 브라우저에서 포트 5500에 연결되지 않습니다 | 대시보드는 컨테이너 안에서 0.0.0.0으로 열어야 호스트 쪽 포트와 이어집니다. 기본값인 127.0.0.1로 열면 컨테이너 밖에서 접속할 수 없습니다 |
| 디스크가 갑자기 찹니다 | 이미지에 약 4GB, 볼륨에 약 2.3GB가 들어갑니다. 이미지의 ~/.hermes 내용이 볼륨으로 한 번 복사되므로 같은 설치본이 두 벌 있습니다 |
이어서 해 볼 것
- 볼륨 구조 확인:
docker volume ls로 데이터 볼륨과 연습용 볼륨이 나뉘어 있는지 보고,docker compose down과docker compose down -v의 차이를 시험해 봅니다. - 옵션 비교: 설치 스크립트의
--channel main은 최신 개발판을 설치합니다. 다른 채널로 빌드해서hermes --version이 달라지는지 비교해 봅니다. - 다음 단계: 로컬 Ollama 모델 연결로 이어서 모델을 붙입니다.
확인 범위
- 해 본 것: 2026-10-24, Windows 11의 Docker 29.5.3과
ubuntu:24.04이미지에서 Hermes Agent v0.22.5(2026.9.24, stable)를 확인했습니다. 설치 명령,hermes --version,hermes doctor,~/.hermes구조, 첫 실행 화면, 대시보드 로그인과 Models 화면은 제가 직접 실행해서 본 것입니다. 설치 방법, 옵션, 플랫폼, 대시보드 인증 요건은 공식 문서(Installation, Web Dashboard)와 맞춰 보았습니다. 문서 내용과 다르게 동작한 곳은 없었습니다. - 해 보지 않은 것: 문서에 안내된
/opt/hermes기반 공식 Docker 이미지, Linux 호스트, macOS, WSL2에서의 직접 설치, Windows 네이티브 설치. - 읽을 때 주의: 비밀번호와 시크릿 값은 실습용 예시입니다. 실제 환경에서 그대로 쓰면 안 됩니다.
이 글의 다음 단계
- n8n으로 웹훅 자동화 만들기: 도커 실행, 워크플로 가져오기, 호출 확인오픈소스 자동화 도구 n8n을 도커로 localhost에만 열어 띄우고, 웹훅을 받아 JSON을 돌려주는 워크플로를 명령줄로 가져와 게시합니다. 게시 전후의 차이, 재시작이 필요했던 점, 한글과 빈 입력과 GET 요청 결과를 확인합니다.
- Uptime Kuma로 서비스 상태 감시하기: 도커 실행, 감시 대상 추가, 정상과 장애 확인오픈소스 모니터링 도구 Uptime Kuma를 도커로 localhost에만 열어 띄우고, 감시 대상 두 개를 등록해 정상(UP)과 장애(DOWN)가 각각 기록되는 것을 확인합니다. 데이터가 도커 볼륨에 남는 방식도 함께 봅니다.