# Hermes Agent를 호스트가 아닌 Docker 컨테이너에 설치하고 첫 실행하기

> 명령을 직접 실행하는 오픈소스 에이전트 Hermes Agent를 Ubuntu 컨테이너 안에 설치 스크립트로 설치하고, 첫 실행 화면, hermes doctor 점검, ~/.hermes 데이터 폴더 구조, 웹 대시보드 로그인까지 직접 확인합니다.

- 주소: https://copyandrun.com/blog/hermes-agent-install-in-docker/
- 분야: AX
- 발행일: 2026-10-24
- 태그: Hermes Agent, Docker, 에이전트, 설치

Hermes Agent는 Nous Research가 공개한 오픈소스 에이전트입니다. 대화만 하는 챗봇과 달리 터미널 명령을 실행하고 파일을 읽고 쓰는 도구를 갖고 있어서, 설치한 컴퓨터에서 할 수 있는 일을 에이전트가 대신 할 수 있습니다. 이 글에서는 그 점을 고려해, 호스트 PC가 아니라 일회용 Docker 컨테이너 안에 설치하는 과정까지 다룹니다. 설치 스크립트 실행, 첫 실행 화면, `hermes doctor` 점검, `~/.hermes` 데이터 폴더, 웹 대시보드 로그인을 직접 확인합니다.

이 글은 Hermes Agent 실무 시리즈의 1편입니다. 이어지는 글에서 로컬 모델 연결, 명령 승인, MCP, 메모리와 스킬을 같은 컨테이너에서 차례로 다룹니다.

- 1편 이 글: 컨테이너에 설치하고 첫 실행하기
- 2편 [로컬 Ollama 모델을 Hermes Agent에 연결하기](/blog/hermes-agent-local-ollama/)
- 3편 [Hermes Agent의 명령 승인 절차 확인하기](/blog/hermes-agent-command-approval/)
- 4편 [Hermes Agent에 MCP filesystem 서버를 붙이고 접근 범위 제한하기](/blog/hermes-agent-mcp-filesystem/)
- 5편 [Hermes Agent의 스킬과 메모리, 저장되는 정보 확인하기](/blog/hermes-agent-skills-and-memory/)

## 왜 호스트가 아니라 컨테이너인가

공식 보안 문서에 따르면 터미널 백엔드의 기본값은 `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 만들기

```bash
mkdir hermes-lab && cd hermes-lab
```

`Dockerfile`을 만듭니다. 설치 스크립트가 필요로 하는 `curl`, `git`, `tar`와 인증서를 먼저 깔고, 일반 사용자 `agent`를 만든 뒤 그 사용자로 설치 스크립트를 실행합니다. `--non-interactive`는 입력이 필요한 단계를 건너뛰는 옵션이고, `--skip-browser`와 `--skip-computer-use`는 이 실습에서 쓰지 않는 브라우저 도구와 화면 제어 도구를 받지 않는 옵션입니다. `tmux`는 이후 글에서 TUI 화면을 파일로 남길 때 쓰며, 직접 실행해 보는 데에는 필요하지 않습니다.

```dockerfile
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 밖으로 노출되지 않게 하려는 것입니다.

```yaml
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. 이미지 만들기

<!-- files: Dockerfile -->

```bash
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. 컨테이너를 띄우고 버전 확인하기

<!-- files: docker-compose.yml -->

```bash
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)
```

![컨테이너가 Up 상태이고 hermes 버전이 v0.22.5로 나오며 실행 사용자가 root가 아닌 agent로 확인되는 터미널](https://copyandrun.com/img/hermes-agent-install-in-docker/01-compose-up.png)

`PORTS` 열이 `127.0.0.1:5500->9119`로 나오면 포트가 내 PC에서만 열린 것입니다. 마지막 줄이 `uid=0(root)`가 아니라 `agent`인지도 꼭 확인합니다.

## 4. hermes doctor로 점검하기

```bash
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)
```

![hermes doctor가 Python 환경과 필수 패키지를 통과로 표시하고 메신저 라이브러리와 로그인 항목만 경고로 표시한 터미널](https://copyandrun.com/img/hermes-agent-install-in-docker/02-doctor.png)

끝부분에는 `Found 4 issue(s) to address`가 나왔습니다. API 키가 아직 없다는 안내 한 건과, 번들된 npm 패키지에 알려진 취약점이 있다는 안내 세 건(루트, web, ui-tui)이었습니다. 취약점 안내는 업스트림 lockfile이 고쳐지기를 기다리라는 내용이고, Docker에서는 다시 빌드한 이미지를 받으라는 안내가 붙습니다. 이번 환경에서 고칠 수 있는 항목이 아니므로 그대로 두었습니다. 모델 연결은 2편에서 합니다.

## 5. 데이터 폴더 구조 보기

```bash
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 홈 폴더 아래의 config.yaml, memories, sessions, skills, logs 같은 폴더와 용량 2.3G가 표시된 터미널](https://copyandrun.com/img/hermes-agent-install-in-docker/03-hermes-home.png)

`~/.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`를 실행합니다.

```bash
docker compose exec -w /home/agent/practice hermes hermes
```

처음 실행하면 사용 통계 공유 여부를 묻는 질문이 먼저 나옵니다. 공유하면 활동량과 오류 종류 같은 집계 값을 Nous에 하루에 한 번 보낸다는 설명이 붙어 있고, 이 글에서는 `No thanks`를 골랐습니다. 나중에 `hermes setup telemetry`로 바꿀 수 있습니다.

![첫 실행에서 사용 통계 공유 여부를 묻고 No thanks가 선택된 화면](https://copyandrun.com/img/hermes-agent-install-in-docker/04-first-run-prompt.png)

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

![시작 화면에서 추론 공급자가 아직 설정되지 않았다고 알리며 설정하겠느냐고 묻는 화면](https://copyandrun.com/img/hermes-agent-install-in-docker/05-first-screen.png)

이 캡처에서는 위쪽의 큰 로고와 도구 목록을 줄였습니다. `hermes doctor`가 설정 파일을 통과로 표시해도 모델은 비어 있으므로, 이 질문이 나오는 것이 정상입니다.

## 7. 웹 대시보드 열어 보기

Hermes에는 설정, 세션, 스킬, MCP, 로그를 브라우저에서 다루는 대시보드가 있습니다. 문서에 따르면 `127.0.0.1`이 아닌 주소에 열면 인증이 필수이며, 인증 설정이 없으면 시작하지 않습니다. 그래서 `docker-compose.yml`에 사용자 이름과 비밀번호를 환경 변수로 넣었습니다. 값은 이 실습용 예시이므로, 다른 환경에서는 반드시 바꿔 쓰십시오.

```bash
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`로 로그인합니다.

![Nous Research 로고 아래에 사용자 이름과 비밀번호를 입력하는 Hermes Agent 대시보드 로그인 화면](https://copyandrun.com/img/hermes-agent-install-in-docker/06-dashboard-login.png)

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

![대시보드 Models 화면에서 기본 모델이 anthropic/claude-opus-4.6으로 표시된 모습](https://copyandrun.com/img/hermes-agent-install-in-docker/07-dashboard-models.png)

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| `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 모델 연결](/blog/hermes-agent-local-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 네이티브 설치.
- **읽을 때 주의:** 비밀번호와 시크릿 값은 실습용 예시입니다. 실제 환경에서 그대로 쓰면 안 됩니다.
