Hermes Agent 아키텍처

Hermes Agent의 실행 모드, 데이터 구조, Entrypoint 동작 방식을 설명합니다.

---

세 가지 실행 모드

명령어	역할	기본 포트
gateway run	메시징 게이트웨이 (Telegram, Discord, Slack, WhatsApp, Signal)	8642
dashboard --host 0.0.0.0	웹 UI 대시보드 (FastAPI + React SPA)	9119
hermes (인자 없음)	CLI TUI (터미널 대화 인터페이스)	-

---

데이터 구조

모든 상태는 단일 볼륨 /opt/data (호스트 ~/.hermes)에 저장:

/opt/data/
├── .env              # API 키, 시크릿 (Provider/Bot Token)
├── config.yaml       # 모델 선택, 에이전트 설정, auxilary provider
├── SOUL.md           # 에이전트 정체성/페르소나
├── sessions/         # 대화 기록 (FTS5 검색 가능)
├── memories/         # 영구 메모리 (Nudge 기반 학습)
├── skills/           # 설치/생성된 스킬 (agentskills.io 호환)
├── cron/             # 정기 작업 정의
├── hooks/            # 이벤트 훅
├── logs/             # 런타임 로그
└── workspace/        # 에이전트 작업 공간

---

Entrypoint 동작 순서

entrypoint.sh (docker/entrypoint.sh):

1. root로 시작 → gosu로 hermes 유저로 권한 하향
2. HERMES_HOME 디렉토리 구조 생성
3. .env.example → .env 복사 (최초 실행 시, 모든 값 주석 처리)
4. cli-config.yaml.example → config.yaml 복사
5. SOUL.md 복사
6. 번들 스킬 동기화 (skills_sync.py)
7. hermes <command> 실행

---

API 키 저장 방식 두 가지

방식	대상	특성
Docker Compose environment:	컨테이너 프로세스 환경변수	Entrypoint가 읽지만 .env 파일에 반영 안 됨
Dashboard /api/env PUT	Hermes 내부 .env 파일	Gateway가 실제로 참조. Dashboard KEYS 탭에서도 관리 가능

---

중요 플래그

dashboard 명령어

플래그	설명
--host 0.0.0.0	모든 네트워크 인터페이스에서 수신 (Docker 필요)
--port 9119	포트 지정
--no-open	브라우저 자동 열기 방지
--insecure	필수 — 0.0.0.0 바인딩 허용 (보안 가드 우회)
--tui	TUI 모드로 실행

gateway 명령어

환경변수	설명
API_SERVER_HOST=0.0.0.0	API 서버 바인딩 주소
API_SERVER_PORT=8642	API 서버 포트
GATEWAY_HEALTH_URL	헬스체크 URL (dashboard → gateway)