Hermes Agent VPS 호스팅 운영 가이드

서비스 운영 중 필요한 관리, 모니터링, 문제 해결 가이드입니다.

💡 요약 정리

운영 핵심 명령어: hermes-setup, hermes-start/stop/restart, hermes-update, hermes-chat
직접 podman 명령 실행 시에는 반드시 su - hermes로 전환 후 수행 (rootless podman)
모델 변경/메신저 추가 후에는 반드시 hermes-restart로 재시작 필요
고가용성은 Credential Pool(같은 프로바이더 키 순환)과 Fallback(다른 프로바이더 전환) 두 기능으로 구성
백업은 내장 hermes backup(zip) 또는 /opt/hermes/data/ tar 보관. 백업 책임은 고객에게 있음

1. 운영 명령어

기본 진입

ssh root@{아이디}.mycafe24.com

설정 메뉴 (hermes-setup)

hermes-setup

============================================================
   Hermes Agent Configuration (Stage 2)
============================================================

  Select an option:

  [1] Full Setup (hermes setup)
  [2] Status Check
  [3] View Logs
  [4] Dashboard Auth Setup (web login)
  [0] Reset Options

  Select (1/2/3/4/0): _

관리 스크립트

명령	설명
`hermes-setup`	대화형 설정 메뉴 (TUI)
`hermes-start`	에이전트 + 대시보드 시작
`hermes-stop`	에이전트 + 대시보드 중지
`hermes-restart`	전체 재시작 (헬스체크 포함)
`hermes-chat`	터미널 대화 인터페이스
`hermes-update`	최신 이미지로 업데이트
`hermes-update --rollback`	이전 이미지로 롤백

모든 관리 스크립트는 root에서 실행 시 hermes 사용자로 자동 위임됩니다.

주요 명령어 트리

hermes-setup                          설정 메뉴
hermes-start                          에이전트 + 대시보드 시작
hermes-stop                           에이전트 + 대시보드 중지
hermes-restart                        전체 재시작
hermes-chat                           터미널 채팅
hermes-update                         최신 이미지로 업데이트
hermes-update --rollback              이전 이미지로 롤백

su - hermes                           hermes 유저로 전환
 ├ podman ps                          컨테이너 상태 확인
 ├ podman logs -f hermes-agent        실시간 로그
 ├ podman logs --tail 100 hermes-agent  최근 100줄 로그
 └ podman exec -it hermes-agent       컨테이너 접속
    ├ hermes status                   에이전트 상태 확인
    ├ hermes model                    AI 모델 확인/변경
    ├ hermes doctor                   시스템 진단
    ├ hermes auth                     자격 증명(키 풀) 관리
    ├ hermes fallback                 폴백 체인 관리
    └ hermes gateway status           게이트웨이(메신저) 상태

직접 podman 명령어를 사용하려면 su - hermes로 전환 후 실행합니다. 컨테이너 안에서 hermes는 PATH에 등록되어 있어 podman exec hermes-agent hermes status처럼 바로 호출할 수 있습니다.

2. 상태 확인

서버(컨테이너) 상태 확인

su - hermes
podman ps

정상 출력:

CONTAINER ID  IMAGE                                       STATUS                 NAMES
a1b2c3d4e5f6  docker.io/nousresearch/hermes-agent:latest  Up 2 hours (healthy)  hermes-agent

에이전트 상태 확인

su - hermes
podman exec hermes-agent hermes status

시스템 진단

su - hermes
podman exec hermes-agent hermes doctor

hermes doctor는 v0.15.1 기준 아래 항목을 점검합니다.

점검 항목	설명
Security Advisories	보안 권고 사항
Python Environment	버전, 가상환경, 버전 파일 일관성
Required Packages	OpenAI SDK, Rich, python-dotenv, PyYAML, HTTPX, Croniter, python-telegram-bot, discord.py
Configuration Files	`.env`, `config.yaml`, config 버전
Auth Providers	Nous Portal, OpenAI Codex, Google Gemini OAuth, MiniMax OAuth, xAI OAuth 등 로그인 상태
Directory Structure	cron, sessions, logs, skills, memories, SOUL.md
상태 DB	`state.db` 세션 수

3. 로그 관리

실시간 로그

su - hermes
podman logs -f hermes-agent

Ctrl+C로 중단.

최근 로그 (지정 줄)

su - hermes
podman logs --tail 50 hermes-agent

파일 기반 로그

su - hermes
cat /opt/hermes/data/logs/agent.log      # 에이전트 로그
cat /opt/hermes/data/logs/errors.log     # 에러 로그
cat /opt/hermes/data/logs/gateway.log    # 게이트웨이 로그
cat /opt/hermes/data/dashboard.log       # 대시보드 로그

systemd 서비스 로그

su - hermes
journalctl --user -u hermes-agent -f

4. 재시작 / 중지 / 시작

에이전트 + 대시보드 재시작 (권장)

hermes-restart

에이전트 + 대시보드 중지

hermes-stop

에이전트 + 대시보드 시작

hermes-start

설정 변경 후에는 반드시 재시작이 필요합니다.
hermes-setup > [1] Full Setup 완료 시 자동 재시작 여부를 묻습니다.
hermes-start는 컨테이너 시작 후 Gateway PID 대기(최대 60초) → Dashboard 자동 시작까지 수행합니다.

대시보드 관리

대시보드 접근:

http://<서버IP>:9119

접속 시 로그인 창이 표시되며, 초기 설정 시 지정한 Username(기본 admin)과 Password로 로그인합니다.

대시보드 로그인 계정 설정/변경:

hermes-setup
# → [4] Dashboard Auth Setup (web login) 선택
# → Username / Password 입력 → 대시보드 자동 재시작

2026-06 보안 강화(hardening)로 공개(0.0.0.0) 바인딩 대시보드는 인증(basic_auth) 설정이 필요합니다. 비밀번호를 잊었을 때도 위 메뉴에서 다시 설정하면 됩니다.

대시보드 상태 확인:

su - hermes -c 'podman exec hermes-agent pgrep -f "hermes dashboard"'
su - hermes -c 'cat /opt/hermes/data/dashboard.log'
su - hermes -c 'systemctl --user status hermes-dashboard'

대시보드만 재시작:

su - hermes -c 'podman exec hermes-agent pkill -f "hermes dashboard"'
hermes-start

대시보드는 hermes-start, hermes-stop, hermes-restart 명령에 포함되어 자동 관리됩니다.

5. AI 모델 변경

방법 1: hermes-setup 에서 변경

hermes-setup
# → [1] Full Setup 선택

기존 설정이 있으면 라디오 메뉴 없이 곧바로 전체 재구성(reconfigure) 위저드가 실행되며, 첫 섹션이 Model & Provider입니다. 각 프롬프트에 현재 값이 기본값으로 표시되므로, 모델/프로바이더 항목만 새로 고르고 나머지는 Enter로 통과하면 됩니다.

방법 2: 모델 섹션만 직접 실행 (권장)

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup model'

또는 hermes model 로 프로바이더/모델을 바로 선택할 수 있습니다.

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes model'

방법 3: 터미널 채팅 중 변경

hermes-chat
# 채팅 중 /model 명령 입력

방법 4: 현재 모델 확인

su - hermes
podman exec hermes-agent hermes status      # 현재 모델/프로바이더 표시

모델 변경 후에는 hermes-restart로 재시작이 필요합니다 (CLI/TUI로 변경한 경우).

6. 메신저 추가/변경

방법 1: 게이트웨이 섹션 실행

hermes-setup
# → [1] Full Setup → Messaging Platforms 단계까지 진행

또는 게이트웨이 섹션만 직접 실행:

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup gateway'

v0.15.1 기준 약 23종 플랫폼 체크리스트가 표시됩니다. 번호로 토글하고 Enter로 확정합니다.

  Toggle by number, Enter to confirm.

  [ ] Telegram        [ ] WeCom Callback (Self-Built App)
  [ ] Discord         [ ] Weixin / WeChat
  [ ] Slack           [ ] BlueBubbles (iMessage)
  [ ] Matrix          [ ] QQ Bot
  [ ] Mattermost      [ ] Yuanbao
  [ ] WhatsApp        [ ] Google Chat
  [ ] Signal          [ ] IRC
  [ ] Email           [ ] LINE
  [ ] SMS (Twilio)    [ ] ntfy
  [ ] DingTalk        [ ] SimpleX
  [ ] Feishu / Lark   [ ] Microsoft Teams
  [ ] WeCom           (+ Webhooks: GitHub/GitLab 등)

표시 순서·구성은 설치된 플러그인에 따라 달라질 수 있습니다 (Discord·Google Chat·IRC·LINE·ntfy·SimpleX·Teams는 플러그인으로 동적 로드).
각 플랫폼별 필요 정보는 초기 설정 가이드 > 2-4. 메시징 플랫폼 설정의 표를 참조하세요.

개별 섹션 CLI 명령어 참고

섹션	CLI 명령어
모델/프로바이더	`hermes setup model`
메시징 플랫폼	`hermes setup gateway`
터미널 백엔드	`hermes setup terminal`
도구	`hermes setup tools`
에이전트 설정	`hermes setup agent`
TTS	`hermes setup tts`

위 명령어는 컨테이너 내부에서 실행합니다:
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup <섹션>'
개별 섹션 실행 후에는 hermes-restart로 게이트웨이를 재시작해야 변경사항이 적용됩니다.

6-1. Credential Pool (같은 프로바이더 복수 키 순환)

Credential Pool은 동일한 프로바이더에 여러 API 키를 등록하고, Rate Limit이나 장애 시 다음 키로 자동 전환하는 기능입니다.

서로 다른 프로바이더 간 전환은 Credential Pool이 아닌 Fallback(6-2 참조)으로 설정합니다.

`hermes auth` 서브커맨드

모든 명령은 컨테이너 내부에서 실행합니다:

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth <명령>'

명령	설명	예시
`auth add <프로바이더>`	API 키 추가	`hermes auth add anthropic`
`auth list`	등록된 전체 키 목록	`hermes auth list`
`auth status <프로바이더>`	프로바이더 인증 상태	`hermes auth status anthropic`
`auth remove <번호/라벨>`	특정 키 삭제	`hermes auth remove 2`
`auth reset <프로바이더>`	쿨다운(소진) 상태 초기화	`hermes auth reset anthropic`
`auth logout <프로바이더>`	인증/로그인 상태 제거	`hermes auth logout nous`

인자 없이 hermes auth만 실행하면 대화형 메뉴(키 추가 / 삭제 / 쿨다운 초기화 / 순환 전략 설정 / 종료)가 표시됩니다.

순환 전략 설정

전략은 인자 없는 hermes auth 대화형 메뉴의 "Set rotation strategy for a provider" 항목에서 선택하거나, config.yaml의 credential_pool_strategies를 직접 편집합니다.

su - hermes -c 'vi /opt/hermes/data/config.yaml'

# config.yaml 최상위 레벨
credential_pool_strategies:
  anthropic: fill_first
  openrouter: round_robin

전략	동작	적합한 상황
`fill_first` (기본)	첫 번째 키 소진 시 다음 키로 전환	주 키 + 백업 키 구성
`round_robin`	요청마다 순차적으로 다음 키 사용	여러 키에 고르게 분산
`least_used`	사용량이 가장 적은 키 우선	실제 사용량 기반 분산
`random`	매 요청 시 랜덤 키 선택	예측 불가능한 분산

쿨다운 동작

에러	쿨다운 시간	의미
429	1시간	Rate Limit 초과 → 다음 키로 자동 전환
402	1시간	과금/쿼터 초과 → 다음 키로 자동 전환

설정 변경 후에는 hermes-restart로 재시작해야 적용됩니다.
TUI(위저드)를 반복 실행하면 .env 키와 수동 등록 키가 충돌할 수 있습니다. 추가 키는 CLI(hermes auth add)로 등록하세요.

6-2. Fallback (다른 프로바이더로 자동 전환)

주 모델이 실패할 때 다른 프로바이더의 모델로 자동 전환하는 기능입니다. 폴백 체인은 등록한 순서대로 시도됩니다.

트리거 조건

상황	동작
Rate Limit(429)	재시도 소진 후 폴백 전환
Overload(503/529)	재시도 소진 후 폴백 전환
Connection Error	폴백 전환

방법 1: `hermes fallback` CLI (권장)

hermes model과 동일한 picker로 폴백 체인을 관리합니다.

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes fallback list'    # 현재 체인 보기
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes fallback add'     # 프로바이더+모델 추가
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes fallback remove'  # 항목 삭제
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes fallback clear'   # 전체 삭제

방법 2: config.yaml 직접 편집

단일 폴백은 fallback_model, 다단계 체인은 fallback_providers를 사용합니다.

# 단일 폴백: Anthropic(주) → OpenRouter
fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

# 다단계 체인 (순차 시도)
fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: minimax
    model: MiniMax-M1-80k
  - provider: kimi-coding
    model: kimi-k2.5

각 폴백 프로바이더의 키를 .env(또는 hermes auth)에 등록해야 합니다.

프로바이더	필요한 인증	비고
`openrouter`	`OPENROUTER_API_KEY`	가장 범용적
`anthropic`	`ANTHROPIC_API_KEY`	Claude 직접 연결
`nous`	OAuth (`hermes portal`)	Nous Research
`minimax`	`MINIMAX_API_KEY`	MiniMax 글로벌
`zai`	`ZAI_API_KEY`	Zhipu GLM
`kimi-coding`	`KIMI_API_KEY`	Moonshot/Kimi
`custom`	`api_key_env`로 지정	자체 호스팅/로컬

설정 후 hermes-restart로 재시작 필수.

6-3. 두 기능 조합 요약

기능	범위	설정 방법
Credential Pool	같은 프로바이더 내 키 순환	`hermes auth add` + 대화형 전략 메뉴 / `credential_pool_strategies`
Fallback	다른 프로바이더로 전환	`hermes fallback add` (CLI) 또는 `fallback_model`/`fallback_providers`

요청 → 주 모델 사용
         │
         ├─ 성공 → 응답
         │
         └─ 실패(429/402) → Credential Pool 내 다음 키로 전환
                              │
                              ├─ 성공 → 응답
                              │
                              └─ 모든 키 소진(429/503/529/연결오류) → Fallback 발동
                                                                      └─ 다른 프로바이더로 전환

7. 설정 리셋

hermes-setup > [0] Reset Options에서 3단계 리셋을 선택할 수 있습니다.

[Reset] Select reset scope:
  [1] Reset Sessions/Memories
  [2] Reset Operational Data
  [3] Factory Reset (Full Wipe)
  [4] Cancel

레벨	삭제 대상	보존 대상	확인
[1] Reset Sessions/Memories	대화 기록, 기억, state.db	설정, API Key, 스킬 전부	y/n
[2] Reset Operational Data	대화·기억·크론·로그·훅·스킬·gateway_state.json·channel_directory.json·SOUL.md	설정(config.yaml), API Key(.env)	y/n
[3] Factory Reset (Full Wipe)	위 전부 + API Key(.env)·캐시·모든 상태 파일. config.yaml은 템플릿에서 복원	config.yaml.template	`yes` 전체 입력

리셋 시 컨테이너가 자동으로 중지 → 데이터 삭제 → 재생성(rm + run) → Dashboard 복구됩니다. (재생성은 데이터 소유권(UID 10000)을 다시 맞추기 위함입니다.)

8. Hermes Agent 업데이트

방법 1: hermes-update 사용 (권장)

hermes-update              # 최신 이미지로 업데이트
hermes-update --rollback   # 문제 시 이전 이미지로 롤백

hermes-update는 다음을 자동 수행합니다.

현재 이미지 ID를 .prev_image에 저장 (롤백 대비)
최신 이미지 다운로드
기존 컨테이너 중지/삭제
동일 보안/리소스 파라미터로 새 컨테이너 생성
데이터 볼륨 유지 (/opt/hermes/data)
Dashboard 재시작

방법 2: 수동 업데이트

su - hermes
podman pull docker.io/nousresearch/hermes-agent:latest
podman stop hermes-agent
podman rm hermes-agent
podman run -d --name hermes-agent --restart unless-stopped \
  --cap-drop=ALL \
  --cap-add=CHOWN --cap-add=DAC_OVERRIDE --cap-add=FOWNER \
  --cap-add=SETUID --cap-add=SETGID \
  --pids-limit=256 \
  --memory=4g --cpus=2 --shm-size=1g \
  --log-opt max-size=10m --log-opt max-file=3 \
  --health-cmd="test -f /opt/data/gateway.pid" --health-interval=30s \
  -p 9119:9119 \
  -v /opt/hermes/data:/opt/data \
  -e TZ=Asia/Seoul \
  -e HERMES_UID=10000 -e HERMES_GID=10000 \
  docker.io/nousresearch/hermes-agent:latest gateway run
systemctl --user restart hermes-agent.service

⚠️ 수동 실행 시 -e HERMES_UID=10000 -e HERMES_GID=10000을 반드시 포함하세요. 누락 시 데이터 볼륨 소유권 불일치로 게이트웨이가 쓰기 실패할 수 있습니다. --memory는 자동 모드(hermes-update)에서는 RAM의 3/4(최대 4g)로 산정됩니다.

업데이트 시 /opt/hermes/data/의 설정과 데이터는 보존됩니다.

9. 데이터 백업

주요 데이터 위치

데이터	경로	설명
설정	`/opt/hermes/data/config.yaml`	메인 설정
API Key	`/opt/hermes/data/.env`	프로바이더 인증 정보
기억	`/opt/hermes/data/memories/`	영구 기억 데이터
대화 기록	`/opt/hermes/data/sessions/`	세션 기록
스킬	`/opt/hermes/data/skills/`	스킬 데이터
크론	`/opt/hermes/data/cron/`	예약 작업
성격	`/opt/hermes/data/SOUL.md`	에이전트 성격 정의

방법 1: 내장 백업 명령 (권장)

설정·스킬·세션·데이터를 zip 한 파일로 묶습니다.

# 전체 백업
su - hermes -c 'podman exec hermes-agent /opt/hermes/.venv/bin/hermes backup -o /opt/data/hermes-backup.zip'
# 핵심 상태만 빠르게
su - hermes -c 'podman exec hermes-agent /opt/hermes/.venv/bin/hermes backup --quick -o /opt/data/hermes-quick.zip'

# 복원
su - hermes -c 'podman exec hermes-agent /opt/hermes/.venv/bin/hermes import /opt/data/hermes-backup.zip'

생성된 zip은 컨테이너의 /opt/data = 호스트 /opt/hermes/data에 떨어지므로 호스트에서 바로 복사·보관할 수 있습니다.

방법 2: 호스트에서 tar 백업 (대안)

su - hermes
tar czf /tmp/hermes-backup-$(date +%Y%m%d).tar.gz /opt/hermes/data/

복원:

su - hermes
podman stop hermes-agent
tar xzf /tmp/hermes-backup-YYYYMMDD.tar.gz -C /
podman start hermes-agent

백업 책임은 고객에게 있습니다. 중요한 데이터는 주기적으로 별도 백업을 권장합니다.

10. 방화벽 관리

항목	기본 설정
인바운드	SSH(22번) + Dashboard(9119번) 허용
아웃바운드	제한 없음
fail2ban	SSH 5회 실패 → 30분 차단

대시보드(9119)는 설정과 API 키를 노출할 수 있으므로, 신뢰하지 않는 네트워크에서는 허용 IP를 제한하는 것을 권장합니다.
나의 서비스 관리 > 서버관리 > 방화벽관리에서 포트별 허용 IP를 추가/삭제할 수 있습니다.

11. 요금 및 연장

플랜	월 요금 (VAT 포함)	사양
Lite	14,000원	공유CPU / 2GB RAM / 40GB SSD / 500GB 트래픽
Core (추천)	33,000원	공유CPU / 4GB RAM / 100GB SSD / 1.2TB 트래픽
Pro	55,000원	공유CPU / 6GB RAM / 150GB SSD / 1.5TB 트래픽

초과 트래픽: 165원/GB (VAT 포함), 월 단위 초기화, 익월 후불
연장/업그레이드: 나의 서비스 관리 > 연장/변경/추가옵션
만료 후 15일 경과 시 데이터 삭제 가능 (복구 불가)

12. 문제 해결

증상	원인	해결
SSH 접속 불가	서버 OFF / 방화벽 차단	나의 서비스 관리에서 ON 확인 + 방화벽 22번 포트 확인
`hermes-setup` 안 됨	컨테이너 미실행	`hermes-start` 실행
AI 응답 없음	API Key 미입력/만료	`hermes setup model` 또는 `hermes model`에서 재입력
텔레그램 봇 무응답	Gateway 미연결 / Token·Allowed User ID 오류	`hermes-setup` > [2] Status Check 확인, Token·ID 재확인
"권한 없음" 에러	root에서 podman 실행	`su - hermes` 후 재실행
컨테이너 크래시	메모리 부족	`podman logs hermes-agent` 확인 후 요금제 업그레이드 검토
키 순환이 안 됨	전략 미설정/충돌	`hermes auth list`로 확인 → 대화형 `hermes auth`에서 전략 재설정
느린 응답	모델/네트워크 이슈	`hermes doctor`로 진단
대시보드 접속 불가	방화벽 차단 / 프로세스 중지	방화벽 9119번 허용 + `hermes-restart`
대시보드 빈 화면	Dashboard 프로세스 미시작	`cat /opt/hermes/data/dashboard.log` 확인 → `hermes-restart`
대시보드 로그인 불가 / 비밀번호 분실	basic_auth 미설정 또는 비밀번호 분실	`hermes-setup` > [4] Dashboard Auth Setup에서 재설정
업데이트 후 문제	새 이미지 호환성	`hermes-update --rollback`으로 이전 이미지 복원

부록. 명령어 빠른 참조

관리 스크립트 (호스트)

명령	설명
`hermes-setup`	대화형 설정 메뉴 (위저드 / 상태 / 로그 / 초기화)
`hermes-start`	에이전트 + 대시보드 시작
`hermes-stop`	에이전트 + 대시보드 중지
`hermes-restart`	전체 재시작 (헬스체크 포함, 설정 변경 후 필수)
`hermes-chat`	터미널 대화 인터페이스
`hermes-update`	최신 이미지로 업데이트
`hermes-update --rollback`	이전 이미지로 롤백

컨테이너 내부 명령

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes <명령>' 형식으로 실행합니다.

명령	설명
`hermes status`	현재 모델/프로바이더/상태 확인
`hermes doctor`	시스템 진단
`hermes model`	프로바이더/모델 변경
`hermes setup <섹션>`	model / gateway / terminal / tools / agent / tts
`hermes auth [add\|list\|status\|remove\|reset\|logout]`	자격 증명(키 풀) 관리
`hermes fallback [list\|add\|remove\|clear]`	폴백 체인 관리
`hermes backup [-o <path>] [--quick]` / `hermes import <zip>`	백업 / 복원
`hermes gateway status`	게이트웨이(메신저) 상태

💡 설정 변경 후에는 대부분 hermes-restart로 재시작이 필요합니다.