본문으로 건너뛰기

Hermes Agent VPS 호스팅 운영 가이드

💡 요약 정리

  • 운영 핵심 명령어: hermes-setup, hermes-start/stop/restart, hermes-update, hermes-chat
  • 직접 podman 명령 실행 시에는 반드시 su - hermes로 전환 후 수행
  • 모델 변경/메신저 추가 후에는 반드시 hermes-restart로 재시작 필요
  • Credential Pool(같은 프로바이더 키 순환), Fallback Model(다른 프로바이더 전환), Smart Routing(복잡도 분기) 세 기능을 조합해 고가용성 구성 가능
  • 백업은 /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
  [0] Reset Options

  Select (1/2/3/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 gateway status           게이트웨이(메신저) 상태

직접 podman 명령어를 사용하려면 su - hermes로 전환 후 실행합니다.

2. 상태 확인

서버 상태 확인

su - hermes
podman ps

정상 출력:

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

에이전트 상태 확인

su - hermes
podman exec hermes-agent hermes status

시스템 진단

su - hermes
podman exec hermes-agent hermes doctor

hermes doctor는 아래 항목을 점검합니다:

점검 항목설명
Python 환경버전, 가상환경 여부
필수 패키지OpenAI SDK, Rich, dotenv 등
설정 파일.env, config.yaml 상태
인증 상태Nous Portal, OpenAI Codex 등
디렉토리cron, sessions, logs, skills, memories
상태 DB세션 수
외부 도구git, Node.js, browser
API 연결설정된 프로바이더

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/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 자동 시작까지 수행합니다.

4-1. 대시보드 관리

대시보드 접근

http://<서버IP>:9119

대시보드 상태 확인

# 대시보드 프로세스 확인
su - hermes -c 'podman exec hermes-agent pgrep -f "hermes dashboard"'

# 대시보드 로그 확인
su - hermes -c 'cat /opt/hermes/data/dashboard.log'

# systemd 서비스 상태
su - hermes -c 'systemctl --user status hermes-dashboard'

대시보드만 재시작

su - hermes -c 'podman exec hermes-agent pkill -f "hermes dashboard"'
# hermes-start가 대시보드를 다시 시작합니다
hermes-start

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

5. AI 모델 변경

방법 1: hermes-setup 기존 사용자 메뉴 사용

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

기존 설정이 있으면 아래 메뉴가 나타납니다:

Welcome Back!

  [1] Quick Setup
  [2] Full Setup
  [3] Model & Provider
  [4] Terminal Backend
  [5] Messaging Platforms (Gateway)
  [6] Tools
  [7] Agent Settings
  [8] Exit

[3] Model & Provider를 선택하면 프로바이더 선택 → API Key → 모델 선택 순서로 변경할 수 있습니다.

방법 2: CLI로 직접 실행

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

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

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

방법 4: 컨테이너 내부에서 현재 모델 확인

su - hermes
podman exec -it hermes-agent hermes model

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

6. 메신저 추가/변경

방법 1: hermes-setup 기존 사용자 메뉴 사용

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

기존 사용자 메뉴에서 [5] Messaging Platforms (Gateway)를 선택합니다.

17개 플랫폼 체크리스트가 나타납니다. Space 키로 선택/해제하고 Enter로 확정합니다:

  (Space: select/deselect, Enter: confirm, Arrow keys: move)

  [ ] Telegram
  [ ] Discord
  [ ] Slack
  [ ] Signal
  [ ] Email
  [ ] SMS (Twilio)
  [ ] Matrix
  [ ] Mattermost
  [ ] WhatsApp
  [ ] DingTalk
  [ ] Feishu / Lark
  [ ] WeCom (Enterprise WeChat)
  [ ] WeCom Callback (Self-Built App)
  [ ] Weixin (WeChat)
  [ ] BlueBubbles (iMessage)
  [ ] QQ Bot
  [ ] Webhooks (GitHub, GitLab, etc.)
  ─────────────────
  Continue →

방법 2: CLI로 직접 실행

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

개별 섹션 CLI 명령어 참고

섹션CLI 명령어
모델/프로바이더hermes setup model
메시징 플랫폼hermes setup gateway
터미널 백엔드hermes setup terminal
도구hermes setup tools
에이전트 설정hermes setup agent
TTShermes 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 Model(6-2 참조)로 설정합니다.

Credential Pool CLI 명령어

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

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 remove <번호>특정 키 삭제hermes auth remove 2
auth strategy <프로바이더>순환 전략 변경hermes auth strategy anthropic
auth reset <프로바이더>쿨다운 상태 초기화hermes auth reset anthropic

프로바이더별 키 등록 예시

Anthropic 키 2개 등록:
# 첫 번째 키
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth add anthropic'
# → Paste your API key: sk-ant-aaaa...
# → Label: anthropic-key-1

# 두 번째 키
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth add anthropic'
# → Paste your API key: sk-ant-bbbb...
# → Label: anthropic-key-2
OpenRouter 키 2개 등록:
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth add openrouter'
# → Paste your API key: sk-or-aaaa...
# → Label: openrouter-key-1

su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth add openrouter'
# → Paste your API key: sk-or-bbbb...
# → Label: openrouter-key-2
*중요: 각 키는 해당 프로바이더에만 등록하세요. OpenRouter 키를 minimax에 넣으면 인증 실패합니다.

순환 전략 설정

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

# config.yaml 최상위 레벨에 추가
credential_pool_strategies:
  anthropic: fill_first
  openrouter: round_robin
CLI 방식: 
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes auth strategy anthropic'
# → [1] Fill-first / sticky
# → [2] Round robin
# → [3] Random
# → 선택: 1
전략동작적합한 상황
fill_first (기본)첫 번째 키 소진 시 다음 키로 전환주 키 + 백업 키 구성
round_robin요청마다 순차적으로 다음 키 사용여러 키에 고르게 부하 분산
random매 요청 시 랜덤 키 선택예측 불가능한 분산
least_used사용량 가장 적은 키 우선 (config.yaml 직접 편집만 가능)실제 사용량 기반 분산

쿨다운 동작

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

설정 변경 후에는 hermes-restart로 재시작해야 적용됩니다.
*주의: TUI를 2회 이상 반복 실행하면 .env 키 자동 시드와 수동 등록 키가 충돌할 수 있습니다. TUI는 최초 1회만 사용하고, 이후 키 추가는 CLI(hermes auth add)로 진행하세요.

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

주 모델이 실패할 때 다른 프로바이더의 모델로 자동 전환하는 기능입니다. 세션당 최대 1회 발동합니다.

TUI에서는 설정 불가. config.yaml 직접 편집으로만 설정합니다.

트리거 조건

HTTP 코드의미동작
429Rate Limit 초과재시도 소진 후 fallback 전환
503서비스 일시 불가재시도 소진 후 fallback 전환
529Overloaded재시도 소진 후 fallback 전환
Connection Error연결 실패즉시 fallback 전환

설정 방법

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

config.yaml의 fallback_model 주석을 해제하고 프로바이더/모델을 지정합니다.

시나리오별 설정 예시

API 키, 봇 토큰 등의 민감 정보는 TUI 및 CLI 화면, 설정 파일 모두에서 ******** 형태로 마스킹 처리되어 제공됩니다. 원문 값은 화면에 노출되지 않습니다.

시나리오 1: Anthropic(주) → OpenRouter(fallback) 
fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

.env에 필요한 키:

ANTHROPIC_API_KEY=********    # 주 모델용
OPENROUTER_API_KEY=********   # fallback용
시나리오 2: Anthropic(주) → MiniMax(fallback) 
fallback_model:
  provider: minimax
  model: MiniMax-M1-80k

.env에 필요한 키:

ANTHROPIC_API_KEY=********    # 주 모델용
MINIMAX_API_KEY=********      # fallback용
시나리오 3: OpenRouter(주) → 로컬 모델(fallback) 
fallback_model:
  provider: custom
  model: llama-3.1-70b
  base_url: http://localhost:11434/v1
  api_key_env: OLLAMA_API_KEY
시나리오 4: 다단계 fallback 체인 (3단계 순차 시도) 
fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: minimax
    model: MiniMax-M1-80k
  - provider: kimi-coding
    model: kimi-k2.5

.env에 각 프로바이더의 키 모두 등록 필요.

fallback에 사용 가능한 프로바이더

프로바이더필요한 환경변수비고
openrouterOPENROUTER_API_KEY가장 범용적 (200+ 모델)
anthropicANTHROPIC_API_KEYClaude 직접 연결
nousOAuth (hermes auth)Nous Research
minimaxMINIMAX_API_KEYMiniMax 글로벌
zaiZAI_API_KEYZhipuAI GLM 모델
kimi-codingKIMI_API_KEYMoonshot/Kimi
customapi_key_env로 지정자체 호스팅/로컬 모델

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

6-3. Smart Model Routing (요청 복잡도별 모델 분기)

짧고 단순한 요청은 저렴한 모델로, 복잡한 요청은 주 모델로 자동 라우팅합니다.

TUI에서는 설정 불가. config.yaml 직접 편집으로만 설정합니다.

설정 방법

# config.yaml에 추가
smart_model_routing:
  enabled: true
  max_simple_chars: 160
  max_simple_words: 28
  cheap_model:
    provider: openrouter
    model: google/gemini-2.5-flash
요청 유형라우팅 대상
160자/28단어 이하 (짧고 단순)cheap_model (예: Gemini Flash)
그 외 (복잡한 요청)주 모델 (예: Claude Opus)

6-4. 세 가지 기능 조합 요약

기능범위설정 방법TUI 지원
Credential Pool같은 프로바이더 내 키 순환CLI (hermes auth add) + config.yamlFull Setup에서 가능 (1회만)
Fallback Model다른 프로바이더로 전환config.yaml 직접 편집불가
Smart Routing요청 복잡도별 모델 분기config.yaml 직접 편집불가
조합 동작 흐름: 
요청 → Smart Routing 판단 (simple/complex)
         │
         ├─ simple → cheap_model 사용
         │
         └─ complex → 주 모델 사용
                        │
                        ├─ 성공 → 응답
                        │
                        └─ 실패 → Credential Pool 내 다음 키로 전환
                                    │
                                    ├─ 성공 → 응답
                                    │
                                    └─ 모든 키 소진 → Fallback Model 발동
                                                       └─ 다른 프로바이더로 전환

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, SOUL.md설정(config.yaml), API Key(.env)y/n
[3] Factory Reset (Full Wipe)위 전부 + API Key, 캐시, 모든 상태 파일. config.yaml은 템플릿에서 복원config.yaml.template'yes' 전체 입력

리셋 시 컨테이너가 자동으로 중지 → 데이터 삭제 → 재시작 → Dashboard 복구됩니다.
리셋 전 symlink 검증 + 경로 화이트리스트 보안 검증이 자동 수행됩니다.

8. Hermes Agent 업데이트

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

# 최신 이미지로 업데이트
hermes-update

# 문제 발생 시 이전 이미지로 롤백
hermes-update --rollback

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

  1. 현재 이미지 ID를 .prev_image에 저장 (롤백 대비)
  2. 최신 이미지 다운로드
  3. 기존 컨테이너 중지/삭제
  4. 동일 보안/리소스 파라미터로 새 컨테이너 생성
  5. 데이터 볼륨 유지 (/opt/hermes/data)
  6. 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 --init --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=3g --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 \
  docker.io/nousresearch/hermes-agent:latest gateway run
systemctl --user restart hermes-agent.service

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

9. 데이터 백업

주요 데이터 위치

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

백업 명령어

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번) 허용
아웃바운드제한 없음
fail2banSSH 5회 실패 → 30분 차단

대시보드(9119)는 설정과 API 키를 노출할 수 있으므로, 신뢰하지 않는 네트워크에서는 허용 IP를 제한하는 것을 권장합니다.

방화벽 설정 변경

나의 서비스 관리 > 서버관리 > 방화벽관리에서 포트별 허용 IP를 추가/삭제할 수 있습니다.

11. 요금 및 연장

요금제

플랜월 요금 (VAT 포함)사양
Lite14,000원공유CPU / 2GB RAM / 40GB SSD / 500GB 트래픽
Core (추천)33,000원공유CPU / 4GB RAM / 100GB SSD / 1.2TB 트래픽
Pro55,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 > [1] Full Setup > model에서 재입력
텔레그램 봇 무응답Gateway 미연결hermes-setup > [2] Status Check 확인
"권한 없음" 에러root에서 podman 실행su - hermes 후 재실행
컨테이너 크래시메모리 부족podman logs hermes-agent로 확인 후 요금제 업그레이드 검토
기억이 안 됨메모리 비활성hermes-setup > [1] Full Setup > agent에서 memory_enabled 확인
느린 응답모델/네트워크 이슈hermes doctor로 진단
대시보드 접속 불가방화벽 차단 / 프로세스 중지방화벽관리에서 9119번 포트 허용 + hermes-restart
대시보드 빈 화면Dashboard 프로세스 미시작cat /opt/hermes/data/dashboard.log 확인 → hermes-restart
업데이트 후 문제새 이미지 호환성hermes-update --rollback으로 이전 이미지 복원