Hermes Agent VPS 호스팅 초기 설정 가이드
💡 요약 정리
- 서비스 신청 후 처음 설정하는 고객을 위한 가이드입니다.
- AI 프로바이더 연결, 메신저 채널 설정, 에이전트 가동까지 완료합니다.
- 이 단계가 끝나면 메신저에서 AI 에이전트와 대화할 수 있습니다.
- Quick Setup(약 5분) 또는 Full Setup(약 15분) 중 선택 가능합니다.
- 필요한 것: SSH 터미널, LLM API Key, (선택) 텔레그램 봇 Token.
사전에 준비해야 할 사항과 두 가지 설정 경로를 한눈에 비교해 보세요.
| 항목 | 내용 |
|---|---|
| 필요한 것 | SSH 접속 가능한 터미널 (Mac: 기본 터미널 / Windows: PowerShell 또는 PuTTY) |
| 소요 시간 | Quick Setup 약 5분 / Full Setup 약 15분 |
| 필요한 정보 | LLM API Key (Anthropic, OpenAI 등), 텔레그램 봇 Token (선택) |
| 경로 | 내용 | 대상 |
|---|---|---|
| Quick Setup (권장) | 프로바이더 + 모델 + 메시징만 설정, 나머지 자동 | 처음 시작하는 분, 빠르게 설정하고 싶은 분 |
| Full Setup | 5개 섹션 전체 설정 (Credential Pool, Vision, TTS 등) | 모든 설정을 직접 제어하고 싶은 분 |
1. 공통 Step 1~3: 서버 접속 ~ 설정 마법사 진입
Step 1. 서버 접속 정보 확인
- 카페24 나의 서비스 관리에 로그인합니다.
- 좌측 메뉴 > 호스팅관리 > Hermes Agent 관리를 클릭합니다.
- 아래 정보를 확인합니다.
| 항목 | 예시 |
|---|---|
| 서버 상태 | ON |
| IP | 172.235.xxx.xxx |
| 호스트명 | {아이디}.mycafe24.com |
| 접속 계정 | root |
서버 상태가 OFF이면 서버원격 관리 버튼을 눌러 ON으로 변경해 주세요.
Step 2. SSH 접속
터미널을 열고 아래 명령어를 입력합니다.
ssh root@{아이디}.mycafe24.com
최초 접속 시 "Are you sure you want to continue connecting?" 메시지가 나오면 yes를 입력합니다.
비밀번호는 서비스 신청 시 설정한 비밀번호입니다.
Step 3. 설정 마법사 실행
SSH 접속 후 아래 명령어를 실행합니다.
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): _
[1] Full Setup을 선택합니다. 확인 프롬프트가 나타나면 y를 입력합니다.
Continue? (y/n): y
컨테이너 내부의 TUI 설정 마법사가 시작되면, Quick Setup과 Full Setup 중 하나를 선택합니다.
How would you like to set up Hermes?
→ (●) Quick setup — provider, model & messaging (recommended)
(○) Full setup — configure everything
2. PATH A: Quick Setup (권장)
대상: 처음 시작하는 분, 빠르게 설정하고 싶은 분
소요 시간: 약 5분 (입력 약 8회)
설정 범위: AI 프로바이더 + 모델 + 메시징 플랫폼만 설정, 나머지 자동 적용
A-1. 프로바이더 선택
라디오 선택 화면에서 사용할 AI 프로바이더를 선택합니다 (화살표 키로 이동, Enter로 확정).
◆ Inference Provider
Choose how to connect to your main chat model.
Select provider:
↑↓ navigate ENTER/SPACE select ESC cancel
(○) Nous Portal (Nous Research subscription)
(○) OpenRouter (100+ models, pay-per-use)
(○) Anthropic (Claude models — API key or Claude Code)
(○) OpenAI Codex
(○) Google AI Studio (Gemini models)
(○) DeepSeek (DeepSeek-V3, R1, coder)
(○) xAI (Grok models)
... (20개+ 프로바이더)
Anthropic (Claude 모델) — API Key 방식
- TUI에서 Anthropic을 선택합니다.
- 인증 방식 선택 화면이 표시됩니다 — 2번 (API key)를 선택합니다.
Choose authentication method:
1. Claude Pro/Max subscription (OAuth login)
2. Anthropic API key (pay-per-token)
3. Cancel
- Anthropic Console에서 API Key를 발급받아 입력합니다.
Paste your API key: ********
✔ API key saved
- 사용할 모델을 선택합니다.
Select model:
(○) claude-opus-4
(○) claude-sonnet-4
(○) claude-haiku-4
...
OpenAI Codex — OAuth 방식
- TUI에서 OpenAI Codex를 선택합니다.
- OAuth 인증 화면이 표시됩니다.
Signing in to OpenAI Codex...
(Hermes creates its own session — won't affect Codex CLI or VS Code)
To continue, follow these steps:
1. Open this URL in your browser:
https://auth.openai.com/codex/device
2. Enter this code:
XXXX-XXXXX
- 내 PC의 브라우저에서 표시된 URL을 열고, 화면에 나타난 코드를 입력합니다.
- OpenAI 계정으로 로그인하면 인증이 완료됩니다.
✔ Authentication successful
- 사용할 모델을 선택합니다.
OpenAI Codex는 API Key 대신 OAuth로 인증하므로, 별도 Key 발급이 필요 없습니다. OpenAI 계정만 있으면 됩니다.
기타 프로바이더
| 프로바이더 | 인증 방식 | 비고 |
|---|---|---|
| OpenRouter | API Key | 200+ 모델을 하나의 Key로 사용 |
| Google AI Studio | API Key | Gemini 모델 직접 연결 |
| DeepSeek | API Key | DeepSeek-V3, R1, Coder |
| xAI | API Key | Grok 모델 |
| Nous Portal | OAuth | Nous Research 구독 |
| GitHub Copilot | GITHUB_TOKEN | GitHub 인증 재사용 |
| Hugging Face | API Key | 20+ 오픈 모델 |
| Xiaomi MiMo | API Key | MiMo-V2 모델 |
| Z.AI / GLM | API Key | Zhipu AI |
| Kimi / Moonshot | API Key | Moonshot AI |
| MiniMax | API Key | 글로벌/중국 엔드포인트 |
| Alibaba / DashScope | API Key | Qwen + 멀티 프로바이더 |
| Arcee AI | API Key | Trinity 모델 |
| Kilo Code | API Key | Kilo Gateway |
A-2. API Key 입력 + 모델 선택
프로바이더를 선택하면 API Key 입력 후, 사용 가능한 모델 목록이 표시됩니다.
봇 토큰, API 키 등의 민감 정보는 입력 시 화면에 ******** 형태로 마스킹 처리되어 표시됩니다. 실제 값은 서버 내부 설정 파일에 안전하게 저장되며, 화면상에 원문이 노출되지 않습니다.
Paste your API key: ********
Select model:
(○) anthropic/claude-opus-4
(○) anthropic/claude-sonnet-4
(○) google/gemini-2.5-pro
...
A-3. 기본값 자동 적용
Quick Setup에서는 아래 항목이 자동으로 설정되며 별도 입력 없이 화면에 결과만 표시됩니다.
✔ Applied recommended defaults:
Max iterations: 90
Tool progress: all
Compression threshold: 0.50
Session reset: inactivity (1440 min) + daily (4:00)
Run `hermes setup agent` later to customize.
| 항목 | 자동 적용 값 | 설명 |
|---|---|---|
| Max iterations | 90 | 대화당 최대 도구 호출 횟수 |
| Tool progress | all | 도구 실행 상태 표시 수준 |
| Compression threshold | 0.50 | 컨텍스트 압축 임계값 |
| Session reset | 1440분 비활동 또는 매일 04:00 | 세션 자동 리셋 조건 |
| TTS | Edge TTS (Microsoft, 무료) | 음성 합성 |
| Terminal Backend | Local (서버 직접 실행) | 코드 실행 환경 |
| Credential Pool | 건너뜀 | 나중에 CLI로 추가 가능 |
| Vision | 건너뜀 | 나중에 Full Setup으로 설정 가능 |
| Tools | 건너뜀 | 나중에 Full Setup으로 설정 가능 |
A-4. 메시징 플랫폼 연동
모델 설정 후 메시징 플랫폼 연동 여부를 묻습니다.
Connect a messaging platform? (Telegram, Discord, etc.)
→ (●) Set up messaging now (recommended)
(○) Skip — set up later with 'hermes setup gateway'
"Set up messaging now"를 선택하면 아래 4. 메시징 플랫폼 설정 섹션으로 이어집니다.
A-5. Quick Setup 완료
✔ Setup complete! You're ready to go.
Launch hermes chat now? (Y/n): _
설정이 완료되면 아래 5. 설정 완료 후 확인 섹션에서 대시보드와 대화 기능을 점 검하세요.
3. PATH B: Full Setup
대상: 모든 설정을 직접 제어하고 싶은 분, Credential Pool·Vision·TTS 등 고급 설정이 필요한 분
소요 시간: 약 15분
설정 범위: 5개 섹션을 순서대로 설정
Section 1: Model & Provider — 프로바이더, 모델, Credential Pool, Vision, TTS
Section 2: Terminal Backend — 코드 실행 환경 선택
Section 3: Agent Settings — 반복 횟수, 압축, 세션 리셋 등
Section 4: Messaging Platforms — 17개 메시징 플랫폼
Section 5: Tools — 도구 설정
B-1. Section 1: Model & Provider
프로바이더 선택 + API Key + 모델
Quick Setup과 동일합니다. 위 A-1, A-2를 참조하세요.
Credential Pool (Full Setup 전용)
모델 선택 후, 동일 프로바이더에 여러 API Key를 등록하여 Rate Limit 시 자동 순환시킬 수 있습니다.
◆ Same-Provider Fallback & Rotation
Hermes can keep multiple credentials for one provider and rotate
between them when a credential is exhausted or rate-limited.
Current pooled credentials for anthropic: 1
Add another credential for same-provider fallback? (y/N): y
→ Paste your API key: ********
→ Label (optional, default: key-2): anthropic-key-2
Provider pool now has 2 credential(s).
Add another credential for same-provider fallback? (y/N): n
Key가 2개 이상이면 순환 전략을 선택합니다.
Select same-provider rotation strategy:
→ (●) Fill-first / sticky — 첫 번째 키 소진 시 다음 키로 전환
(○) Round robin — 요청마다 순차적으로 다음 키 사용
(○) Random — 매 요청 시 랜덤 키 선택
| 전략 | 동작 |
|---|---|
| Fill-first / sticky | 첫 번째 키 소진 시 다음 키로 전환 (기본값) |
| Round robin | 요청마다 순차적으로 다음 키 사용 |
| Random | 매 요청 시 랜덤 키 선택 |
*주의: TUI를 2회 이상 재실행하면 .env 키와 수동 등록 키가 충돌할 수 있습니다.
권장: TUI에서 최초 1회만 설정하고, 이후 추가 키는 CLI(hermes auth add <프로바이더>)로 등록하세요.
Vision (Full Setup 전용)
이미지 분석 백엔드를 설정합니다.
(○) OpenRouter (uses Gemini)
(○) OpenAI-compatible endpoint
(○) Skip for now
TTS (Full Setup 전용)
음성 합성 프로바이더를 선택합니다.
(○) OpenAI TTS
(○) ElevenLabs (high-quality)
(○) MiniMax (Chinese-friendly)
(○) Mistral Voxtral (French-friendly)
(○) Edge TTS (Microsoft, default — free)
(○) NeuTTS (local, open-source)
(○) Keep current
B-2. Section 2: Terminal Backend
코드 실행 환경을 선택합니다. 기본값은 Local입니다.
◆ Terminal Backend
Choose where Hermes runs shell commands and code.
Select terminal backend:
(○) Local - run directly on this machine (default)
(○) Docker - isolated container with configurable resources
(○) Modal - serverless cloud sandbox
(○) SSH - run on a remote machine
(○) Daytona - persistent cloud development environment
(○) Singularity/Apptainer - HPC-friendly container
→ (●) Keep current (local)
| 백엔드 | 추가 입력 | 적합한 상황 |
|---|---|---|
| Local | 작업 디렉토리, sudo 비밀번호 (선택) | 기본 설정, 대부분의 사용자 |
| Docker | 이미지, CPU/RAM/GPU | 격리된 실행 환경이 필요할 때 |
| Modal | 인증 모드, 토큰, CPU/RAM/GPU | 서버리스 클라우드 실행 |
| SSH | host, user, port, key path | 원격 머신에서 코드 실행 |
| Daytona | API 키, 이미지, CPU/RAM/GPU | 영구적 클라우드 개발 환경 |
| Singularity | 이미지, CPU/RAM/GPU | HPC 환경 |
특별한 이유가 없으면 Local 또는 Keep current를 선택하세요.
B-3. Section 3: Agent Settings
대화 동작 관련 설정을 진행합니다.
최대 반복 횟수
Maximum tool-calling iterations per conversation.
Default is 90, which works for most tasks. Use 150+ for open exploration.
Max iterations [90]: _
도구 진행 표시
Tool Progress Display
off — Silent, just the final response
new — Show tool name only when it changes
all — Show every tool call with a short preview
verbose — Full args, results, and debug logs
Tool progress mode [all]: _
컨텍스트 압축
Automatically summarizes old messages when context gets too long.
Compression threshold (0.5-0.95) [0.50]: _
세션 리셋 정책
Session reset mode:
→ (●) Inactivity + daily reset (recommended)
(○) Inactivity only (reset after N minutes of no messages)
(○) Daily only (reset at a fixed hour each day)
(○) Never auto-reset
(○) Keep current settings
| 모드 | 추가 입력 | 기본값 |
|---|---|---|
| Inactivity + daily | 비활동 시간(분) + 리셋 시각(시) | 1440분, 04시 |
| Inactivity only | 비활동 시간(분) | 1440분 |
| Daily only | 리셋 시각(0-23시) | 04시 |
| Never | 없음 | - |
B-4. Section 4: Messaging Platforms
17개 메시징 플랫폼 체크리스트가 표시됩니다. 아래 4. 메시징 플랫폼 설정 섹션을 참조하세요.
B-5. Section 5: Tools
도구 설정을 진행합니다. 사용할 도구셋을 토글로 선택하고, 필요한 API 키를 입력합니다.
B-6. Full Setup 완료
설정 요약 출력
"Launch hermes chat now?" (Y/n): _
설정이 완료되면 아래 5. 설정 완료 후 확인 섹션으로 이동합니다.
4. 메시징 플랫폼 설정
플랫폼 선택 (체크리스트)
Space 키로 원하는 플랫폼을 선택/해제하고, 화살표로 이동합니다. 선택이 끝나면 Enter를 누릅니다.
◆ Messaging Platforms
Connect to messaging platforms to chat with Hermes from anywhere.
Select platforms to configure:
Toggle by number, Enter to confirm.
[ ] 1. Telegram
[ ] 2. Discord
[ ] 3. Slack
[ ] 4. Signal
[ ] 5. Email
[ ] 6. SMS (Twilio)
[ ] 7. Matrix
[ ] 8. Mattermost
[ ] 9. WhatsApp
[ ] 10. DingTalk
[ ] 11. Feishu / Lark
[ ] 12. WeCom (Enterprise WeChat)
[ ] 13. WeCom Callback (Self-Built App)
[ ] 14. Weixin (WeChat)
[ ] 15. BlueBubbles (iMessage)
[ ] 16. QQ Bot
[ ] 17. Webhooks (GitHub, GitLab, etc.)
Toggle # (or Enter to confirm): _
Telegram 설정 (권장)
Telegram을 선택하면 아래 3가지 정보를 입력합니다.
1) Bot Token 발급- 텔레그램에서 @BotFather를 검색합니다.
/newbot을 입력 → 봇 이름 설정 → Bot Token을 발급받습니다.- 발급된 Token을 TUI에 입력합니다.
Telegram bot token: ********
✔ Telegram token saved
- 텔레그램에서 @userinfobot을 검색합니다.
/start를 입력하고 표시되는 숫자 Id 값을 확인합니다.- 확인된 Id를 TUI에 입력합니다.
🔒 Security: Restrict who can use your bot
To find your Telegram user ID:
1. Message @userinfobot on Telegram
2. It will reply with your numeric ID (e.g., 123456789)
Allowed user IDs (comma-separated, leave empty for open access): 123456789
✔ Telegram allowlist configured - only listed users can use the bot
📬 Home Channel: where Hermes delivers cron job results,
cross-platform messages, and notifications.
Use your user ID (123456789) as the home channel? (Y/n): y
✔ Telegram home channel set to 123456789
Allowed User IDs에 값을 입력한 경우 → 첫 번째 ID를 Home Channel로 제안합니다.
비워둔 경우 → "Home channel ID (leave empty to set later):"에서 직접 입력합니다.
지원 메시징 플랫폼 (17개) 필요 정보
| 플랫폼 | 필요 정보 |
|---|---|
| Telegram | Bot Token + Allowed User IDs + Home Channel ID |
| Discord | Bot Token + Allowed Users + Home Channel ID |
| Slack | App-Level Token + Bot Token |
| Signal | HTTP Server URL |
| Sender Email Address | |
| SMS (Twilio) | Account SID + Auth Token + From Number |
| Matrix | Server URL + Auth (Token/Password) + Home Channel |
| Mattermost | Server URL + Token + Team + Channel |
| Phone Number ID + Business Account ID + Access Token | |
| DingTalk | Client ID + Client Secret |
| Feishu / Lark | App ID + App Secret |
| WeCom | Bot ID |
| WeCom Callback | Corp ID + Secret + Token + AES Key |
| Weixin | Account ID |
| BlueBubbles | Server URL |
| QQ Bot | App ID + Token + Secret |
| Webhooks | 확인만 (자동 활성화) |
플랫폼 설정 후 서비스 등록
Install gateway as systemd service? (y/n): y
Start the service now? (y/n): y
이미 서비스가 설치된 환경에서는 대신 "Restart the gateway to pick up changes? (Y/n)"이 표시됩니다.
메시징 플랫폼은 나중에 언제든 추가/변경할 수 있습니다.
5. 설정 완료 후 확인
호스트 복귀 및 재시작
TUI 마법사가 종료되면 호스트로 복귀하여 게이트웨이 재시작 여부를 묻습니다.
Gateway restart required to apply changes.
Restart Gateway? (y/n): y
Restarting Gateway...
[OK] Restart complete
설정이 정상적으로 완료되면 아래 화면이 표시됩니다.
============================================================
Setup Complete - Quick Reference
============================================================
Dashboard : http://<호스트IP>:9119
hermes-chat Open terminal chat
hermes-setup Run this setup menu again
hermes-start Start agent + dashboard
hermes-stop Stop agent + dashboard
hermes-restart Restart agent + dashboard
hermes-update Update to latest image
hermes-update --rollback Roll back to previous image
============================================================
대시보드 접속
http://{아이디}.mycafe24.com:9119
또는
http://{서버IP}:9119
| 기능 | 설명 |
|---|---|
| 에이전트 상태 확인 | Gateway 실행 상태, 연결된 플랫폼 등 |
| 로그 조회 | 에이전트 동작 로그 실시간 확인 |
| 설정 관리 | 웹 UI를 통한 설정 조회/변경 |
대시보드는 포트 9119에서 동작합니다. 접속이 안 되면 방화벽에서 9119 포트가 허용되어 있는지 확인하세요.
대시보드는 설정과 API 키를 노출할 수 있으므로, 신뢰하지 않는 네트워크에서는 허용 IP를 제한하는 것을 권장합니다.
터미널에서 대화 시작
hermes-chat
텔레그램에서 대화 시작
설정한 텔레그램 봇에게 메시지를 보내면 AI가 응답합니다.
상태 확인
hermes-setup
# → [2] Status Check 선택
6. 기존 사용자 재설정 (Welcome Back 메뉴)
이미 설정이 완료된 상태에서 hermes-setup > [1] Full Setup을 다시 실행하면 아래 메뉴가 표시됩니다.
◆ Welcome Back!
✔ You already have Hermes configured.
What would you like to do?
→ (●) Quick Setup - configure missing items only
(○) Full Setup - reconfigure everything
(○) Model & Provider
(○) Terminal Backend
(○) Messaging Platforms (Gateway)
(○) Tools
(○) Agent Settings
(○) Exit
| 선택 | 동작 |
|---|---|
| Quick Setup | 누락된 필수 항목만 검사 + 입력 |
| Full Setup | 5개 섹션 전체 재설정 |
| Model & Provider | 프로바이더/모델만 변경 |
| Terminal Backend | 코드 실행 환경만 변경 |
| Messaging Platforms | 메시징 플랫폼만 추가/변경 |
| Tools | 도구 설정만 변경 |
| Agent Settings | 에이전트 동작 설정만 변경 |
개별 섹션 실행 후에도 hermes-restart로 Gateway 재시작이 필요합니다.
CLI로 직접 실행도 가능합니다.
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup model'
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup gateway'
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup agent'
7. Quick vs Full 비교표
| 항목 | Quick Setup | Full Setup |
|---|---|---|
| 프로바이더 + API Key + 모델 | O | O |
| 메시징 플랫폼 | O (Yes/Skip 선택) | O (Section 4) |
| Credential Pool (다중 키 등록) | X (건너뜀) | O |
| Vision (이미지 분석) | X (건너뜀) | O |
| TTS (음성 합성) | 자동 (Edge TTS) | O (6개 중 선택) |
| Terminal Backend | 자동 (Local) | O (6개 중 선택) |
| Agent Settings | 자동 (기본값) | O (직접 설정) |
| Tools | X (건너뜀) | O |
| 소요 시간 | ~5분 | ~15분 |
| 입력 횟수 | ~8회 | ~20회+ |
처음 설정하는 분은 Quick Setup을 권장합니다. 나중에 hermes-setup 재실행으로 개별 섹션을 추가 설정할 수 있습니다.
8. 관리 스크립트 빠른 참조
| 명령 | 설명 |
|---|---|
hermes-setup | 대화형 설정 메뉴 (TUI) |
hermes-start | 에이전트 + 대시보드 시작 |
hermes-stop | 에이전트 + 대시보드 중지 |
hermes-restart | 전체 재시작 (헬스체크 포함) |
hermes-chat | 터미널 대화 인터페이스 |
hermes-update | 최신 이미지로 업데이트 |
hermes-update --rollback | 이전 이미지로 롤백 |
9. 문제가 발생했을 때
| 증상 | 해결 |
|---|---|
| SSH 접속 불가 | 나서관에서 서버 ON 확인 + 방화벽관리에서 22번 포트 IP 확인 |
| hermes-setup 실행 안 됨 | 서버 ON 확인. 재접속 후 다시 시도 |
| API Key 오류 | hermes-setup > [1] Full Setup에서 재입력 |
| 텔레그램 봇 응답 없음 | Bot Token과 사용자 ID 재확인 |
| 대시보드(9119) 접속 불가 | 방화벽관리에서 9119번 포트에 접속 IP 추가 + hermes-restart 실행 |
| 대시보드 빈 화면 | cat /opt/hermes/data/dashboard.log 확인 → hermes-restart |
| 서비스 응답 없음 | hermes-restart로 전체 재시작 |
| 업데이트 후 문제 발생 | hermes-update --rollback으로 이전 이미지 복원 |
| TUI 재실행 후 키 꼬임 | hermes auth list로 확인 → hermes auth remove로 정리 → hermes auth add로 재등록 |
Credential Pool CLI 관리, Cross-Provider Fallback, Smart Model Routing 등 고급 설정은 운영 가이드를 참조하세요.