Hermes Agent VPS 호스팅 초기 설정 가이드

💡 요약 정리

서비스 신청 후 처음 설정하는 고객을 위한 가이드입니다.
AI 프로바이더 연결, 메신저 채널 설정, 도구 설정, 대시보드 로그인 설정, 에이전트 가동까지 완료합니다.
이 단계가 끝나면 메신저에서 AI 에이전트와 대화할 수 있습니다.
본 가이드는 Full Setup(35종+ 프로바이더 중 직접 선택, 약 10분)을 기준으로 설명합니다.
필요한 것: SSH 터미널 / LLM API Key(Anthropic·OpenAI 등) / (선택) 텔레그램 봇 Token.

사전에 준비해야 할 사항입니다.

항목	내용
필요한 것	SSH 접속 가능한 터미널 (Mac: 기본 터미널 / Windows: PowerShell 또는 PuTTY)
소요 시간	Full Setup 약 10분
필요한 정보	LLM API Key(Anthropic·OpenAI 등) + 텔레그램 봇 Token(선택)

💡 Anthropic(Claude), OpenAI, Google 등 원하는 프로바이더를 직접 연결하려면 Full Setup을 사용하세요.

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
  [4] Dashboard Auth Setup (web login)
  [0] Reset Options

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

[1] Full Setup을 선택합니다. 확인 프롬프트가 나타나면 y를 입력합니다.

Continue? (y/n): y

메뉴 항목명은 Full Setup이지만, 선택 시 컨테이너 내부의 hermes setup 위저드가 실행되어 그 안에서 Quick / Full을 다시 고릅니다.

컨테이너 내부 TUI 설정 마법사가 시작되면 Full setup을 선택합니다. (↑↓ 이동, Enter 확정)

How would you like to set up Hermes?

  ○ Quick Setup (Nous Portal) — free OAuth login, no API keys, model + tools
  ● Full setup — configure every provider, tool & option yourself (bring your own keys)

위 화면에서 두 항목이 보이면 Full setup을 선택하세요. 본 가이드는 Full setup을 기준으로 진행합니다.

2. Full Setup 본 흐름

Full Setup은 아래 대화형 4개 섹션 + Agent Settings(자동 적용)로 진행됩니다.

Section 1: Model & Provider    — 35종+ 프로바이더 중 선택, 인증, 모델
Section 2: Terminal Backend    — 코드 실행 환경 선택
(Agent Settings)               — 자동 적용 (비대화형, 'hermes setup agent'로 조정)
Section 3: Messaging Platforms — 약 23종 메시징 플랫폼
Section 4: Tools               — 도구 설정

📝 구버전의 "5개 섹션(Credential Pool·Vision·TTS 포함)" 구성은 v0.15.1에서 바뀌었습니다. Agent Settings는 더 이상 대화형으로 묻지 않고, Credential Pool·Vision·TTS는 위저드에서 분리되어 기본값으로 적용된 뒤 전용 명령으로 관리합니다.

2-1. Section 1: Model & Provider

hermes model과 동일한 프로바이더 선택 화면이 표시됩니다. (↑↓ 이동, Enter/Space 선택, Esc 취소) 처음에는 아직 프로바이더가 없으므로 Warning: No inference provider configured... 안내가 함께 표시되는데 정상입니다.

◆ Inference Provider
  Choose how to connect to your main chat model.
     Guide: https://hermes-agent.nousresearch.com/docs/integrations/providers

Select provider:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel

  → (●) Nous Portal (Everything your agent needs, 300+ models with bundled tool use)
     (○) OpenRouter (Pay-per-use API aggregator)
     (○) NovitaAI (Cloud: Model API, Agent Sandbox, GPU Cloud)
     (○) LM Studio (Local desktop app with built-in model server)
     (○) Anthropic (Claude models via API key or Claude Code)
     (○) OpenAI ▸ (Codex CLI or direct OpenAI API)
     (○) Qwen Cloud / DashScope (Qwen + multi-provider)
     (○) xAI Grok ▸ (Direct API or SuperGrok / Premium+ OAuth)
     (○) Xiaomi MiMo (MiMo-V2.5 and V2 models)
     (○) Tencent TokenHub (Hy3 Preview)
     (○) NVIDIA NIM (Nemotron models)
     (○) GitHub Copilot ▸ (GitHub token API 또는 copilot --acp)
     (○) Hugging Face Inference Providers
     (○) Google Gemini ▸ (AI Studio API or OAuth + Code Assist)
     (○) DeepSeek (V3, R1, coder, direct API)
     (○) Z.AI / GLM (Zhipu direct API)
     (○) Kimi / Moonshot ▸ (Coding Plan, 글로벌 · 중국 엔드포인트)
     (○) StepFun Step Plan (Agent / coding 모델)
     (○) MiniMax ▸ (Global, OAuth Coding Plan & China)
     (○) Ollama Cloud (ollama.com)
     (○) Arcee AI (Trinity 모델)
     (○) GMI Cloud (Multi-model direct API)
     (○) Kilo Code (Kilo Gateway API)
     (○) OpenCode ▸ (Zen pay-as-you-go 또는 Go subscription)
     (○) AWS Bedrock (Claude, Nova, Llama, DeepSeek)
     (○) Azure Foundry (OpenAI-style 또는 Anthropic-style 엔드포인트)
     (○) Qwen OAuth (로컬 Qwen CLI 로그인 재사용)
     (○) Alibaba Cloud Coding Plan (전용 coding tier)
     (○) custom (direct API)
     (○) Custom endpoint (enter URL manually)
     (○) Configure auxiliary models...

일부 벤더는 ▸로 표시된 그룹 행으로 묶여 있습니다(예: OpenAI ▸ → Codex / 직접 API, Google ▸ → AI Studio / OAuth, Kimi ▸ / MiniMax ▸ / xAI ▸ / OpenCode ▸ / GitHub Copilot ▸). 그룹을 선택하면 하위 항목을 다시 고릅니다. 목록은 v0.15.1 실제 화면 기준이며, 설치된 플러그인에 따라 일부 항목이 가감될 수 있습니다.

추천: 처음이라면 Anthropic(Claude) 또는 OpenAI를 권장합니다.

예시 ① Anthropic (Claude) — API Key

Anthropic을 선택합니다.
인증 방식을 선택합니다. (구독 OAuth / API Key / Claude Code 자격증명 중 택1)

Choose authentication method:
  ...
  - Claude Pro/Max subscription (OAuth login)
  - Anthropic API key (pay-per-token)
  - Claude Code credentials (감지 시)

Anthropic Console에서 발급한 API Key를 입력합니다. (입력값은 ********로 마스킹)
사용할 Claude 모델을 선택합니다.

예시 ② OpenAI Codex — OAuth

프로바이더에서 OpenAI ▸ → OpenAI Codex를 선택하면 device-code 로그인이 시작됩니다.

Not logged into OpenAI Codex. Starting login...

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

Waiting for sign-in... (press Ctrl+C to cancel)

내 PC 브라우저에서 위 URL을 열고 표시된 코드를 입력해 OpenAI 계정으로 로그인합니다. (별도 API Key 불필요)
로그인이 완료되면 기본 모델이 자동 설정됩니다.

Login successful!
  Auth state: ~/./auth.json
  Config updated: /opt/data/config.yaml (model.provider=openai-codex)

Default model set to: gpt-5.5 (via OpenAI Codex)

예시 ③ Custom endpoint — 카페24 LLM Router (₩1,000 무료 크레딧)

카페24 LLM Router를 사용하면 100종+ AI 모델을 하나의 API 키로 연결할 수 있고, 가입 시 ₩1,000 무료 크레딧으로 바로 시작할 수 있습니다. 프로바이더 화면에서 Custom endpoint를 선택하고 Base URL https://llm-router.cafe24.com/api/v1 와 API 키를 입력하면 됩니다.

👉 가입부터 API 키 발급, Custom endpoint 연결, 호환 모드 선택까지 한 번에 보려면 LLM Router API로 연결하기 (₩1,000 무료 크레딧)를 참고하세요.

민감 정보(API Key·봇 토큰)는 입력 시 화면에 ********로 마스킹되며, 서버 내부 설정 파일에 안전하게 저장됩니다.

📝 Credential Pool · Vision · TTS 는 별도 명령
v0.15.1에서는 이 항목들을 위저드에서 묻지 않고 기본값(키 순환 off / Vision 자동 감지 / TTS = Edge)으로 적용합니다. 필요 시 아래로 설정하세요. (자세한 내용은 운영 가이드 > 6-1. Credential Pool 참조)

동일 프로바이더 다중 키 등록·순환: hermes auth add <프로바이더>
음성 합성(TTS) 변경: hermes setup tts (OpenAI / ElevenLabs / MiniMax / Mistral Voxtral / Edge / NeuTTS 등)
이미지 분석(Vision) 변경: hermes setup 의 vision 단계

2-2. Section 2: Terminal Backend

코드 실행 환경을 선택합니다. 기본값은 Local입니다.

◆ Terminal Backend
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	기본 설정, 대부분의 사용자
Docker	격리된 실행 환경
Modal	서버리스 클라우드 실행
SSH	원격 머신에서 코드 실행
Daytona	영구 클라우드 개발 환경
Singularity	HPC 환경

특별한 이유가 없으면 Local 또는 Keep current를 선택하세요.

2-3. Agent Settings (자동 적용)

v0.15.1에서는 에이전트 동작 설정을 대화형으로 묻지 않습니다. 아래 권장 기본값이 자동 적용되며 결과만 표시됩니다.

✔ Applied recommended defaults:
  Max iterations: 150
  Tool progress: all
  Compression threshold: 0.50
  Session reset: never (use /reset or compression)
  Run `hermes setup agent` later to customize.

항목	자동 적용 값	설명
Max iterations	150	대화당 최대 도구 호출 횟수
Tool progress	all	도구 실행 상태 표시 수준
Compression threshold	0.50	컨텍스트 압축 임계값
Session reset	never (none)	자동 리셋 안 함 (`/reset` 또는 압축으로 관리)
TTS	Edge TTS (Microsoft, 무료)	음성 합성 기본값
Terminal Backend	Local	코드 실행 환경
Credential Pool	건너뜀	나중에 `hermes auth add`로 추가
Vision	자동 감지	메인 프로바이더 기준 자동

값을 직접 조정하려면 설정 완료 후 다음을 실행하세요.

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

2-4. Section 3: Messaging Platforms (메시징 플랫폼)

AI 프로바이더 연결이 끝나면 메신저 채널을 연결합니다. 번호로 토글하고 Enter로 확정합니다. v0.15.1 기준 약 23종을 지원합니다.

◆ Messaging Platforms
  Connect to messaging platforms to chat with Hermes from anywhere.

  Select platforms to configure (toggle by number, Enter to confirm):

  [ ]  1. Telegram          [ ] 13. WeCom Callback (Self-Built App)
  [ ]  2. Discord           [ ] 14. Weixin / WeChat
  [ ]  3. Slack             [ ] 15. BlueBubbles (iMessage)
  [ ]  4. Matrix            [ ] 16. QQ Bot
  [ ]  5. Mattermost        [ ] 17. Yuanbao
  [ ]  6. WhatsApp          [ ] 18. Google Chat
  [ ]  7. Signal            [ ] 19. IRC
  [ ]  8. Email             [ ] 20. LINE
  [ ]  9. SMS (Twilio)      [ ] 21. ntfy
  [ ] 10. DingTalk          [ ] 22. SimpleX
  [ ] 11. Feishu / Lark     [ ] 23. Microsoft Teams
  [ ] 12. WeCom             (+ Webhooks: GitHub/GitLab 등)

  Toggle # (or Enter to confirm): _

표시 순서·구성은 설치된 플러그인에 따라 달라질 수 있습니다. (Discord·Google Chat·IRC·LINE·ntfy·SimpleX·Teams는 플러그인으로 동적 로드됩니다.)

Telegram 설정 (권장)

Telegram을 선택하면 아래 3가지 정보를 입력합니다.

1) Bot Token 발급

텔레그램에서 @BotFather를 검색합니다.
/newbot 입력 → 봇 이름 설정 → Bot Token을 발급받습니다.
발급된 Token을 TUI에 입력합니다. (********로 마스킹)

2) 사용자 ID 확인 (보안 설정)

텔레그램에서 @userinfobot을 검색하고 /start를 입력합니다.
표시되는 숫자 Id를 확인해 입력합니다.

Allowed user IDs (comma-separated, leave empty for open access): 123456789
✔ Telegram allowlist configured - only listed users can use the bot

3) Home Channel (알림 채널)

크론 작업 결과·알림을 전달받을 채널입니다. DM이면 본인 User ID를 그대로 사용합니다.

Home channel ID (or leave empty to set later with /set-home in Telegram): 123456789
✔ Telegram home channel set to 123456789

나중에 텔레그램 대화창에서 /set-home을 입력해 설정할 수도 있습니다.

주요 플랫폼별 필요 정보

플랫폼	필요 정보
Telegram	Bot Token + Allowed User IDs + Home Channel ID
Discord	Bot Token + Allowed Users + Home Channel ID
Slack	App-Level Token(xapp-) + Bot Token(xoxb-)
Matrix	Homeserver URL + Access Token(또는 ID/PW) + Home Room
Mattermost	Server URL + Bot Token + Team + Channel
WhatsApp	Phone Number ID + Business Account ID + Access Token
Signal	signal-cli REST API URL
Email	발신 이메일 주소(SMTP/IMAP)
SMS	Twilio Account SID + Auth Token + From Number
DingTalk	Client ID + Client Secret
Feishu / Lark	App ID + App Secret
WeCom / WeCom Callback	Bot ID 또는 Corp ID + Secret + Token + AES Key
BlueBubbles	Server URL + Password
QQ Bot	App ID + Token + Secret
Microsoft Teams	Graph 앱 등록 정보
Google Chat / LINE / ntfy / SimpleX / IRC / Yuanbao	각 플랫폼별 토큰·엔드포인트
Webhooks	확인만 (자동 활성화)

플랫폼 설정 후 적용

Restart the gateway to pick up changes? (Y/n): y

메시징 플랫폼은 나중에 hermes setup gateway로 언제든 추가/변경할 수 있습니다. (자세한 내용은 운영 가이드 > 6. 메신저 추가/변경 참조)

2-5. Section 4: Tools (도구 설정)

메시징 설정이 끝나면 마지막으로 도구(Tools) 설정이 이어집니다. 도구는 플랫폼별로 따로 구성됩니다 — 먼저 🖥️ CLI(터미널)에 대해 한 번, 그다음 연결한 메신저(예: 📱 Telegram)에 대해 한 번, 같은 절차를 반복합니다.

💡 권장
도구 항목은 기본 제공된 설정(체크 상태)을 그대로 유지하는 것을 권장합니다. 대부분 API 키 없이 바로 동작하며, 필요한 도구만 나중에 hermes setup tools로 켜면 됩니다.

1) 도구 활성화 체크리스트 (🖥️ CLI)

스페이스로 토글, Enter로 확정합니다. 기본 체크 상태를 유지하고 Enter로 넘어가는 것을 권장합니다.

Tools for 🖥️  CLI
  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel

 → [✓] 🔍 Web Search & Scraping  (web_search, web_extract)
   [✓] 🌐 Browser Automation  (navigate, click, type, scroll)
   [✓] 💻 Terminal & Processes  (terminal, process)
   [✓] 📁 File Operations  (read, write, patch, search)
   [✓] ⚡ Code Execution  (execute_code)
   [✓] 👁️  Vision / Image Analysis  (vision_analyze)
   [ ] 🎬 Video Analysis  (requires video-capable model)
   [✓] 🎨 Image Generation  (image_generate)
   [ ] 🎬 Video Generation  (text-to-video + image-to-video)
   [ ] 🐦 X (Twitter) Search  (requires xAI OAuth or XAI_API_KEY)
   [ ] 🧠 Mixture of Agents  (mixture_of_agents)  [no API key]
   [✓] 🔊 Text-to-Speech  (text_to_speech)
   [✓] 📚 Skills  (list, view, manage)
   [✓] 📋 Task Planning  (todo)
   [✓] 💾 Memory  (persistent memory across sessions)
   [ ] 🧩 Context Engine  (runtime tools from the active context engine)
   [✓] 🔎 Session Search  (search past conversations)
   [✓] ❓ Clarifying Questions  (clarify)
   [✓] 👥 Task Delegation  (delegate_task)
   [✓] ⏰ Cron Jobs  (create/list/update/pause/resume/run)
   [✓] 📨 Cross-Platform Messaging  (send_message)
   [ ] 🏠 Home Assistant  (smart home device control)  [no API key]
   [ ] 🎵 Spotify  (playback, search, playlists, library)
   [ ] 🤖 Yuanbao  (group info, member queries, DM)
   [✓] 🖱️  Computer Use (macOS)  (background desktop control)

체크된 항목 중 일부(예: Computer Use(macOS), X Search 등)는 서버 환경이나 키가 없으면 실제로는 비활성화됩니다. 그대로 두어도 문제 없습니다.

활성화한 도구 중 제공자(provider) 선택이 필요한 항목은 차례로 선택 화면이 뜹니다. 아래 권장값(추가 키·구독 불필요)을 따르면 바로 사용할 수 있습니다.

2) 🌐 Browser Automation → Local Browser (권장)

Local Browser(내장 Chromium, 무료, 키 불필요)를 선택합니다.

--- 🌐 Browser Automation - Choose a provider ---

   (●) Local Browser [★ recommended · free] — Headless Chromium, no API key needed
   (○) Camofox [free · local] — Anti-detection browser (Firefox/Camoufox)
   (○) Browser Use [paid] — Cloud browser with remote execution
   (○) Browserbase [paid] — Cloud browser with stealth and proxies
   (○) Firecrawl [paid] — Cloud browser with remote execution
   (○) Skip — keep defaults / configure later

3) 🎨 Image Generation → Codex 인증이면 OpenAI(Codex auth), 아니면 Skip

이미지 생성은 별도 이미지 API 키가 있거나 OpenAI Codex OAuth로 연동한 경우에만 설정하고, 그 외에는 Skip(권장) 하세요.

Codex(OpenAI) OAuth로 연결한 경우: 제공자에서 OpenAI (Codex auth) [free] 를 선택하면 API 키 없이 ChatGPT/Codex 계정으로 이미지를 생성할 수 있습니다.

Choose a provider:

   (○) FAL.ai [paid] — flux-2, gpt-image, nano-banana 등
   (○) Krea [paid] — Krea 2 foundation model
   (○) OpenAI [paid] — gpt-image-2 (API 키 필요)
   (●) OpenAI (Codex auth) [free] — gpt-image-2 via ChatGPT/Codex OAuth — no API key required
   (○) xAI Grok Imagine (image) [paid] — uses xAI Grok OAuth or XAI_API_KEY
   (○) Skip — keep defaults / configure later

이어서 모델을 고릅니다. 기본값 gpt-image-2-medium 을 권장합니다.

 → (●) gpt-image-2-medium  ~40s   Balanced — default          ← currently in use
   (○) gpt-image-2-low     ~15s   Fast iteration, lowest cost
   (○) gpt-image-2-high    ~2min  Highest fidelity, strongest prompt adherence

별도 이미지 키도, Codex 연동도 없는 경우: Skip — keep defaults / configure later 를 선택하세요. 나중에 hermes setup tools로 추가할 수 있습니다.

4) 🔊 Text-to-Speech → Microsoft Edge TTS (권장)

Microsoft Edge TTS(무료, 키 불필요, 기본 활성)를 선택합니다.

Choose a provider:

   (●) Microsoft Edge TTS [★ recommended · free] — Good quality, no API key needed [active]
   (○) OpenAI TTS [paid] — High quality voices
   (○) ElevenLabs [paid] — Most natural voices
   (○) Google Gemini TTS [preview] — 30 prebuilt voices
   (○) KittenTTS / Piper [local · free] — 로컬 TTS, 키 불필요
   (○) Skip — keep defaults / configure later

5) 🔍 Web Search & Scraping → DuckDuckGo(ddgs) (권장)

키가 필요 없는 DuckDuckGo (ddgs) 를 선택합니다. (프리미엄 검색이 필요하면 Exa/Tavily/Firecrawl 등에서 키를 입력)

Select Search Provider:

   (○) Brave Search (Free) [free] — Free-tier API key — 2k queries/mo
   (●) DuckDuckGo (ddgs) [free · no key · search only] — 키 불필요
   (○) Exa [paid] — Semantic + neural web search
   (○) Firecrawl [paid] — Full search + extract
   (○) Tavily [paid] — Search + extract in one provider
   (○) SearXNG [free · self-hosted] — 자체 호스팅
   (○) Skip — keep defaults / configure later

위 제공자 화면에서 구독형 옵션이 기본(●)으로 선택되어 보일 수 있습니다. 별도 키·구독이 없다면 위 권장값(Local Browser / Edge TTS / DuckDuckGo)을 직접 골라야 추가 비용·로그인 없이 바로 동작합니다.

6) 메신저(📱 Telegram) 도구 — CLI와 동일하게 적용

CLI 도구 설정이 끝나면 연결한 메신저(예: Telegram)에 대해 같은 체크리스트가 한 번 더 표시됩니다. CLI에서 고른 설정을 그대로 유지하면 됩니다 — 기본 체크 상태 그대로 Enter로 넘어가면 CLI용 설정값이 메신저에도 동일하게 적용됩니다.

Tools for 📱 Telegram
  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel

  (🖥️ CLI과 동일한 항목 · 동일한 기본 체크 상태 — 그대로 Enter)

각 묶음이 끝나면 ✓ Saved 🖥️ CLI tool configuration, ✓ Saved 📱 Telegram tool configuration 저장 메시지가 표시되고, 기존 설정은 자동 백업됩니다.

Previous config backed up to: /opt/data/config.yaml.bak.YYYYMMDD_HHMMSS

2-6. 설정 요약 및 완료

모든 섹션이 끝나면 도구 가용성 요약과 완료 화면이 출력됩니다.

◆ Tool Availability Summary
  7/10 tool categories available:

   ✓ Vision (image analysis)
   ✗ Mixture of Agents (missing OPENROUTER_API_KEY)
   ✗ Web Search & Extract (missing EXA_API_KEY, TAVILY_API_KEY, ...)
   ✓ Browser Automation (Local browser)
   ✓ Image Generation (OpenAI (Codex auth))
   ✓ Text-to-Speech (Edge TTS)
   ✗ Skills Hub (GitHub) (missing GITHUB_TOKEN)
   ✓ Terminal/Commands
   ✓ Task Planning (todo)
   ✓ Skills (view, create, edit)

⚠ Some tools are disabled. Run 'hermes setup tools' to configure them,
⚠ or edit ~/./.env directly to add the missing API keys.

┌─────────────────────────────────────────────────────────┐
│              ✓ Setup Complete!                          │
└─────────────────────────────────────────────────────────┘

📁 All your files are in ~/./:
   Settings:  /opt/data/config.yaml
   API Keys:  /opt/data/.env
   Data:      /opt/data/cron/, sessions/, logs/

✗ 표시된 도구는 해당 API 키가 없어 비활성 상태일 뿐 정상입니다. 나중에 hermes setup tools 또는 .env에 키를 추가하면 활성화됩니다.

이 화면 다음, 위저드가 호스트로 복귀하며 게이트웨이 재시작을 묻습니다(아래 3. 설정 완료 후 확인).

3. 설정 완료 후 확인

호스트 복귀 및 재시작

위저드 안에서 도구 설정·요약(2-5/2-6)까지 끝나면, 호스트로 복귀하여 게이트웨이 재시작 여부를 한 번 더 묻습니다.

  Gateway restart required to apply changes.
  Restart Gateway? (y/n): y
    Restarting Gateway...
    [OK] Restart complete

재시작 확인이 두 번 나올 수 있습니다 — 위저드 안의 메시징 단계(Restart the gateway to pick up changes?)에서 한 번, 그리고 위저드 종료 후 호스트 메뉴(Restart Gateway?)에서 한 번입니다. 둘 다 y로 진행하면 됩니다.

설정이 정상 완료되면 빠른 참조가 표시됩니다.

============================================================
   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
============================================================

대시보드 로그인 설정 (Dashboard Auth)

모든 설정이 끝나면 웹 대시보드 로그인 계정을 설정합니다. 다시 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): _

[4] Dashboard Auth Setup을 선택하고, 대시보드 로그인에 사용할 계정 정보를 입력합니다.

[Dashboard Auth] Configure web dashboard login (basic_auth)
  2026-06 hardening: a public (0.0.0.0) bind requires an auth provider.
  Username [admin]:
  Password:
  Password (confirm):

항목	입력 내용
Username	로그인 아이디 (Enter만 누르면 기본값 `admin`)
Password	로그인 비밀번호
Password (confirm)	비밀번호 재입력 (확인)

입력을 마치면 비밀번호가 해시로 저장되고 대시보드가 자동 재시작됩니다.

  Generating hash + updating config.yaml...
CONFIG_OK
  [OK] dashboard.basic_auth set (username=admin)
  Restarting dashboard...
  [OK] Dashboard ready
    URL : http://<서버IP>:9119
    ID  : admin   (password: 방금 설정한 값)

위 [OK] Dashboard ready 메시지가 나오면 정상적으로 접속할 수 있는 상태입니다.

📝 대시보드 인증이 필수인 이유
2026-06 보안 강화(hardening)로 대시보드가 외부에서 접속 가능한 공개(0.0.0.0) 바인딩일 때는 인증(basic_auth) 설정이 필요합니다. 로그인 계정을 설정해야 외부 브라우저에서 대시보드를 사용할 수 있습니다.

대시보드 접속

http://{아이디}.mycafe24.com:9119

접속하면 로그인 창이 표시됩니다. 위에서 설정한 Username(기본 admin)과 Password로 로그인합니다.

기능	설명
에이전트 상태 확인	Gateway 실행 상태, 연결된 플랫폼 등
로그 조회	에이전트 동작 로그 실시간 확인
설정 관리	웹 UI를 통한 설정 조회/변경

카페24 나의 서비스 관리 > 호스팅관리 > Hermes Agent 관리의 대시보드 열기 버튼으로도 접속할 수 있습니다.

대시보드는 포트 9119에서 동작합니다. 접속이 안 되면 방화벽에서 9119 포트가 허용되어 있는지 확인하세요.
설정과 API 키가 노출될 수 있으므로 신뢰하지 않는 네트워크에서는 허용 IP를 제한하는 것을 권장합니다.

터미널에서 대화 시작

hermes-chat

텔레그램에서 대화 시작

설정한 텔레그램 봇에게 메시지를 보내면 AI가 응답합니다.

상태 확인

hermes-setup
# → [2] Status Check 선택

4. 기존 사용자가 재설정할 때

이미 설정이 완료된 상태에서 hermes-setup > [1] Full Setup을 다시 실행하면 라디오 메뉴 없이 곧바로 전체 재구성(reconfigure) 위저드가 실행됩니다. 각 프롬프트에 현재 값이 기본값으로 표시되며, Enter로 유지·새 값 입력으로 변경합니다.

◆ Reconfigure
✔ You already have Hermes configured.
  Running the full wizard — each prompt shows your current value.
  Press Enter to keep it, or type a new value to change it.

  Tip: jump straight to a section with
       'hermes setup model|terminal|gateway|tools|agent',
       or fill only missing items with --quick.

특정 섹션만 바꾸거나 누락 항목만 채우려면 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'

# 누락된 필수 항목만 채우기
su - hermes -c 'podman exec -it hermes-agent /opt/hermes/.venv/bin/hermes setup --quick'

개별 섹션 실행 후에도 hermes-restart로 Gateway 재시작이 필요합니다.

운영 명령어, 상태 확인, 로그 관리, 모델 변경, Credential Pool·Fallback, 백업, 업데이트, 문제 해결은 운영 가이드를 참조하세요.