Back to all posts
Hermes

Hermes Agent 설치와 실행 환경

Proxmox 위 Ubuntu VM에 Hermes Agent를 설치하고, 실제 운영에 맞춰 다중 프로필 환경으로 확장한 과정을 정리했습니다.

2026년 07월 31일8분

Hermes를 처음 접할 때는 개인 PC에 설치해 단일 비서로 실행하는 구성이 이해하기 쉽습니다. 우리도 단테랩스의 Hermes × Codex로 세우는 AI 가상 오피스 자료를 출발점으로 삼았습니다. 환경 준비부터 Codex 인증, Hermes 설치, 메신저 연결, Dashboard, 멀티 프로필까지 전체 순서를 파악하기 좋았기 때문입니다.

다만 실제로 운영할 환경은 조금 달랐습니다. 개인 PC나 WSL보다 계속 켜 둘 서버가 필요했고, 한 명의 비서보다는 역할과 권한을 나눈 여러 프로필을 운영하려 했습니다. 그래서 강의 예제를 그대로 복제하지 않고 Proxmox 위 Ubuntu Server VM에 Hermes를 설치했습니다. 메신저는 Telegram 대신 Slack을 선택했고, Gateway는 사용자 systemd 서비스로 상시 운영합니다.

이 글은 범용 설치 강의가 아닙니다. 현재 ubuntu-hermes 환경이 어떤 기반 위에 있고, 설치 후 무엇을 바꿔 지금의 운영 구조가 되었는지 실제 서버 기록을 따라 정리한 글입니다. 서버 명령과 수치는 2026-07-31의 최초 검증 기록을 기준으로 하며, 개정 과정에서 현행 공식 설치 주소와 CLI 동작을 같은 날 다시 대조했습니다. upstream 차이처럼 계속 바뀌는 값은 당시 출력과 재검증 결과를 구분해 적었습니다.

먼저 정한 운영 방향

설치를 시작하기 전에 우리 환경에서 지킬 기준부터 정했습니다.

  • 개인 PC나 WSL이 아니라 Proxmox 위 Ubuntu Server VM에 설치한다.
  • Telegram 중심 예제가 아니라 Slack 기반 다중 직원 운영을 선택한다.
  • 단일 비서가 아니라 역할과 권한이 분리된 회사 프로필을 구성한다.
  • Gateway는 사용자 systemd 서비스로 상시 운영한다.
  • 비밀정보는 프로필별 .env에 두고 문서에는 변수명과 저장 위치만 남긴다.
  • 현재 Hermes CLI에서 검증한 명령과 보안 동작을 우선한다.

이 기준을 먼저 잡아 두니 Docker를 어디에 쓸지, Hermes를 어떤 방식으로 실행할지, 프로필별 파일을 어디에 둘지가 자연스럽게 정리됐습니다.

서버 구성

2026-07-31 서버에서 확인한 구조입니다. Hermes는 Proxmox 호스트에 직접 설치하지 않고 Ubuntu Server VM 안에 두었습니다.

GMKtec NucBox M6 Ultra
└─ Proxmox VE
   └─ Ubuntu Server 24.04 VM
      ├─ Tailscale
      ├─ Docker Engine + Compose
      ├─ Git / Node.js / Codex CLI
      └─ Hermes Agent
         ├─ default profile
         ├─ named profiles
         ├─ profile별 Gateway
         ├─ shared skills
         └─ Dashboard

아래 표는 최초 검증과 이번 개정 때 VM에서 확인한 기준값입니다. 설치 명령을 따라 하기 전에 같은 버전을 맞춰야 한다는 뜻은 아닙니다. 우리가 어떤 환경에서 운영 기록을 남겼는지 보여 주기 위한 값입니다.

항목 확인값
OS Ubuntu 24.04.4 LTS
Kernel 6.8.0-124-generic
CPU 4 vCPU
Memory 5.7GiB
Docker Engine 29.6.0
Docker Compose v5.1.4
Tailscale 1.98.4, service active
Git 2.43.0
Node.js v24.16.0
npm 11.13.0
Codex CLI 0.145.0
Hermes Agent v0.19.0, git install
Hermes Python 3.11.15

상위 Proxmox 하드웨어와 스토리지 값은 과거 구축 기록에 남아 있습니다. 다만 이번 글을 작성할 때는 호스트에 직접 접속해 다시 검증하지 않았습니다. 여기서는 확인한 VM 값과 과거 기록의 경계를 구분합니다.

19인치 서버 랙 선반에 장착된 Intel NUC 미니 PC 8대

미니 PC 기반 서버 운영을 보여주는 참고 사진입니다. 실제 Littleducks 장비와는 다릅니다. 사진: Truenetworks, CC BY-SA 3.0.

설치 과정

1. 서버 기본 도구와 Docker 준비

Shell history에서 확인한 첫 단계는 Ubuntu 패키지 업데이트와 Docker 공식 저장소 등록입니다. Docker Engine, containerd, Buildx, Compose plugin을 설치한 뒤 hello-world 컨테이너가 실행되는지 확인했고, 버전과 서비스 상태도 함께 점검했습니다.

당시 실행 흐름은 아래와 같습니다.

sudo apt update
sudo apt install -y ca-certificates curl
# Docker 공식 APT 저장소 등록
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world
docker --version
docker compose version
systemctl is-active docker

여기서 Docker는 Hermes를 담는 컨테이너가 아닙니다. Hermes 자체는 Ubuntu VM에 직접 설치했습니다. Docker는 이후 격리 실행, 자동화, 별도 서비스 확장을 위한 기반으로 남겨 두었고, Hermes의 기본 terminal backend는 local로 운영합니다.

2. Git과 Codex CLI 준비

다음으로 Git, curl, 인증서 패키지를 확인하고 Codex CLI 설치 스크립트를 실행했습니다. 설치 후에는 실행 경로를 잡고 버전을 확인했습니다.

sudo apt install -y curl git ca-certificates
curl -fsSL https://chatgpt.com/codex/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
codex --version

이 서버에는 데스크톱 화면이 없습니다. Codex 인증에는 headless server 환경에서 사용할 수 있는 device authentication을 썼습니다. Shell history에는 로그인 명령과 최소 응답을 확인한 명령이 남아 있습니다.

codex login --device-auth
codex exec --skip-git-repo-check "Reply only with: codex ok"

API key를 문서나 shell history에 직접 남기는 대신 OAuth credential을 사용했습니다. 현재 OpenAI Codex provider 운영도 이 방식에서 시작했습니다.

3. Hermes 설치

Hermes 저장소의 파일 생성 시각과 Git reflog를 확인하면 설치일은 2026-06-23입니다. 당시 shell history에는 아래 명령이 남아 있습니다.

curl -fsSL \
  https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \
  | bash

2026-07-31 개정 시점에도 공식 문서에서 안내하는 CLI 설치 진입점은 다음 주소입니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

설치 후에는 git 설치본, 실행 명령, default profile home이 각각 아래 경로에 생겼습니다.

/home/littleduck/.hermes/hermes-agent   # git 설치본
/home/littleduck/.local/bin/hermes      # 실행 명령
/home/littleduck/.hermes/               # default profile home

시간 기록도 함께 대조했습니다. Git reflog의 최초 기록은 2026-06-23 07:58:56 UTC clone이고, /home/littleduck/.local/bin/hermes의 생성 시각은 같은 날 07:59:49 UTC입니다.

4. 모델을 설정하고 첫 응답 확인

초기에는 OpenAI Codex provider와 GPT-5.5를 기본값으로 설정했습니다. 설정 파일만 만들어졌는지 보는 데서 끝내지 않고, 구성 검사와 one-shot 응답까지 확인했습니다.

hermes config set model.provider openai-codex
hermes config set model.default gpt-5.5
hermes config check
hermes --oneshot "Reply only with: hermes ok"

2026-07-31 개정 시점에는 역할별 프로필 대부분이 gpt-5.6-sol, default가 gpt-5.6-sol-pro, Lipa가 gpt-5.5를 사용합니다. 설정을 바꿀 때는 YAML을 직접 수정하기보다 아래 인터페이스를 기준으로 삼습니다.

hermes setup
hermes model
hermes config set <key> <value>
hermes doctor

프로필이 늘어나면 경로부터 이해해야 합니다

단일 프로필로 시작할 때는 경로 구분이 크게 어렵지 않습니다. 프로필이 여러 개가 되면 어떤 파일이 공통이고 어떤 파일이 프로필 전용인지 먼저 알아야 합니다. Hermes의 주요 파일은 profile home을 기준으로 해석합니다.

$HERMES_HOME/config.yaml    설정
$HERMES_HOME/.env           비밀정보
$HERMES_HOME/SOUL.md        역할·행동 기준
$HERMES_HOME/profile.yaml   profile description
$HERMES_HOME/skills/        profile 전용 skills
$HERMES_HOME/memories/      장기 기억
$HERMES_HOME/state.db       세션 상태 저장소
$HERMES_HOME/logs/           실행 로그

Named profile은 다음 구조를 사용합니다.

/home/littleduck/.hermes/profiles/<profile-id>/

프로필마다 같은 skill을 복사하면 수정본이 갈라질 수 있습니다. 그래서 회사 공통 skill의 단일 정본은 별도 공용 루트에 둡니다.

/home/littleduck/.hermes/shared-skills/

각 프로필의 skills.external_dirs가 이 공용 루트를 가리킵니다. 최초 검증일인 2026-07-31에 default와 named profile을 합한 12개 환경에서 공용 skill이 검색되는지 확인했습니다. 개정 시점의 hermes profile list에서도 같은 12개 환경이 확인됐습니다.

설치 후 hermes doctor에서 확인한 것

설치가 끝났다고 바로 운영 준비가 끝나는 것은 아니었습니다. hermes doctor로 인증, 설정 파일, 상시 실행 조건과 주변 도구 상태를 한 번에 확인했습니다.

  • Hermes v0.19.0과 config schema v33 정상
  • OpenAI Codex 로그인 정상
  • profile별 .env, config.yaml, SOUL.md, session DB 존재
  • systemd linger 활성화
  • Git, Docker, Node.js 사용 가능
  • built-in memory active
  • 당시 hermes --version은 설치본이 upstream보다 125 commits 뒤에 있다고 표시
  • web/ui-tui workspace의 build-time dependency advisory가 남아 있음
  • 일부 선택 도구는 provider credential 또는 시스템 의존성이 없어 비활성 상태

개정 검토에서 upstream을 다시 가져와 git으로 직접 비교한 값은 136 commits였습니다. upstream이 계속 움직이므로 125와 136은 고정된 제품 사양이 아니라 각각의 확인 시점에 나온 상태값입니다.

마지막 세 항목은 설치 실패를 뜻한다고 단정할 수 없습니다. 업데이트가 가능하다는 사실과 지금 업데이트해야 한다는 결정도 다릅니다. Hermes update는 프로필, Gateway, Dashboard와 플러그인 호환성에 영향을 줄 수 있으므로 변경 기록과 회귀 검증 범위를 먼저 정한 뒤 수행합니다.

확인한 사실과 운영 판단의 경계

서버에서 확인한 사실

  • 현재 Hermes는 Docker container가 아니라 Ubuntu VM의 git 설치본으로 실행된다.
  • terminal backend는 local이다.
  • 비밀정보와 설정은 분리되어 있다.
  • 기본 인증 provider는 OpenAI Codex다.
  • server boot 이후 지속 실행이 필요한 Gateway는 systemd user service를 사용한다.

현재 구조에 대한 판단

현재 구조는 단일 개인 비서보다 작은 회사 조직을 장기간 운영하는 용도에 적합하다고 판단했습니다. 다만 여러 profile이 같은 VM의 local filesystem을 공유합니다. Hermes 공식 문서가 설명하는 profile 분리는 각 profile home의 설정, 인증정보, 기억, 세션, skill과 상태를 나누는 논리적 격리이며, 같은 OS 계정이 접근하는 파일 시스템 전체를 보안 경계로 분리하는 방식은 아닙니다.

고객 데이터나 서로 다른 보안등급의 작업을 넣을 때는 이 차이를 먼저 봐야 합니다. Hermes가 지원하는 Docker·SSH backend나 별도 VM·별도 계정 같은 추가 격리를 검토해야 합니다.

지금 적용하고 있는 운영 기준

현재 운영에서는 아래 기준을 따릅니다.

  • Proxmox host가 아니라 Ubuntu VM 안에 Hermes를 유지한다.
  • Hermes 기본 실행은 local backend를 사용한다.
  • 설정은 hermes config set과 공식 setup 명령을 우선한다.
  • 비밀 값은 .env 또는 인증 저장소에만 두며 Wiki에 기록하지 않는다.
  • 업데이트는 자동 적용하지 않고 변경 영향과 롤백을 기록한 뒤 수행한다.

아직 정하지 않은 항목도 있습니다. Hermes upstream update 적용 시점, build-time npm advisory의 실제 운영 영향과 해소 일정은 추가 검토가 필요합니다. 고객 프로젝트용 profile을 현재 VM에 둘지 별도 격리 환경으로 분리할지도 정해지지 않았습니다. VM·Proxmox backup 보존 기간과 복구 시험 방식 역시 미결정 상태입니다.

설치 자체는 한 번의 스크립트로 시작할 수 있었습니다. 그다음부터는 경로, 인증정보, 프로필 분리 수준과 업데이트 기준을 우리 운영 방식에 맞추는 일이 이어졌습니다. 이 글에 남긴 명령과 수치는 그 과정에서 실제로 확인한 기록이며, 미확인 항목과 운영 판단은 따로 구분했습니다.

출처