웹 대시보드

웹 대시보드는 Hermes 에이전트 설치를 관리하기 위한 브라우저 기반 UI입니다. YAML 파일을 편집하거나 CLI 명령어를 실행하는 대신, 깔끔한 웹 인터페이스에서 설정을 구성하고 API 키를 관리하며 세션을 모니터링할 수 있습니다.

빠른 시작

hermes dashboard

이는 로컬 웹 서버를 시작하고 브라우저에서 http://127.0.0.1:9119 를 엽니다. 대시보드는 완전히 사용자의 컴퓨터에서 실행되며, 데이터가 로컬호스트를 벗어나지 않습니다.

옵션

플래그	기본값	설명
--port	9119	웹 서버를 실행할 포트
--host	127.0.0.1	바인드 주소
--no-open	—	브라우저를 자동으로 열지 마세요
--insecure	꺼짐	로컬호스트가 아닌 호스트에 바인딩 허용 (위험함 — 네트워크에 API 키가 노출됨; 방화벽과 강력한 인증과 함께 사용)
--tui	꺼짐	브라우저 내 채팅 탭을 표시합니다 (hermes --tui를 PTY/WebSocket을 통해 내장). 또는 HERMES_DASHBOARD_TUI=1을 설정합니다.

# Custom port
hermes dashboard --port 8080

# Bind to all interfaces (use with caution on shared networks)
hermes dashboard --host 0.0.0.0

# Start without opening browser
hermes dashboard --no-open

전제 조건

기본 hermes-agent 설치에는 HTTP 스택이나 PTY 헬퍼가 포함되어 있지 않습니다 — 이것들은 선택적 추가 기능입니다. 웹 대시보드는 FastAPI와 Uvicorn(web 추가)이 필요합니다. 채팅 탭 또한 내장된 TUI를 의사 터미널 뒤에서 실행하기 위해 ptyprocess가 필요합니다(pty POSIX 추가). 둘 다 다음과 같이 설치하세요:

pip install 'hermes-agent[web,pty]'
``web` 추가 항목은 FastAPI/Uvicorn을 포함합니다; `pty`은 `ptyprocess` (POSIX) 또는 `pywinpty` (네이티브 Windows — 포함된 TUI 자체는 여전히 WSL이 필요함)을 포함합니다. `pip install hermes-agent[all]`에는 두 가지 추가 항목이 모두 포함되어 있으며, 메시징/음성 등도 원할 경우 가장 쉬운 경로입니다.

의존성 없이 `hermes dashboard`를 실행하면 설치할 항목을 알려줍니다. 프런트엔드가 아직 빌드되지 않았고 `npm`가 사용 가능한 경우, 첫 실행 시 자동으로 빌드됩니다.

## 페이지 \{#pages}

### 상태 \{#status}

랜딩 페이지에는 설치 상태에 대한 실시간 개요가 표시됩니다:

- **에이전트 버전** 및 출시일
- **게이트웨이 상태** — 실행/중지, PID, 연결된 플랫폼 및 상태
- **활성 세션** — 지난 5분 동안 활성화된 세션 수
- **최근 세션** — 모델, 메시지 수, 토큰 사용량 및 대화 미리보기가 포함된 가장 최근 20세션 목록

상태 페이지는 5초마다 자동으로 새로 고쳐집니다.

### 채팅 \{#chat}

**채팅** 탭은 전체 Hermes TUI를 브라우저에 직접 내장합니다 (`hermes --tui`에서 사용하는 동일한 인터페이스). 터미널 TUI에서 할 수 있는 모든 것 — 슬래시 명령, 모델 선택기, 도구 호출 카드, 마크다운 스트리밍, clarify/sudo/승인 프롬프트, 스킨 테마 설정 — 이곳에서도 똑같이 작동합니다. 왜냐하면 대시보드가 실제 TUI 바이너리를 실행하고 [xterm.js](https://xtermjs.org/)를 통해 ANSI 출력을 렌더링하며, WebGL 렌더러로 픽셀 단위 셀 레이아웃을 처리하기 때문입니다.

**작동 방식:**

- `/api/pty`는 대시보드의 세션 토큰으로 인증된 WebSocket을 엽니다
- 서버는 POSIX 의사 터미널 뒤에서 `hermes --tui`을 생성합니다
- 키 입력은 PTY로 전달되고; ANSI 출력은 브라우저로 다시 스트리밍됩니다
- xterm.js의 WebGL 렌더러는 각 셀을 정수 픽셀 그리드에 그립니다; 마우스 추적(SGR 1006), 와이드 문자(유니코드 11), 그리고 박스 그리기 글리프 모두 네이티브로 렌더링됩니다
- 브라우저 창 크기를 조정하면 `@xterm/addon-fit` 애드온을 통해 TUI 크기가 조정됩니다

**기존 세션 재개:** **세션** 탭에서 원하는 세션 옆의 재생 아이콘(▶)을 클릭합니다. 그러면 `/chat?resume=<id>`로 이동하고 `--resume`와 함께 TUI가 실행되며 전체 기록을 불러옵니다.

**필수 조건:**

- Node.js (`hermes --tui`와 동일한 요구 사항; TUI 번들은 첫 실행 시 빌드됩니다)
- `ptyprocess` — `pty` 추가 기능에 의해 설치됨 (`pip install 'hermes-agent[web,pty]'` 또는 `[all]` 모두를 포함함)
- POSIX 커널(Linux, macOS 또는 WSL2). `/chat` 터미널 창은 특히 POSIX PTY가 필요합니다 — 네이티브 Windows Python에는 이에 상응하는 것이 없으므로, 네이티브 Windows 설치에서는 대시보드의 나머지 부분(세션, 작업, 메트릭, 구성 편집기)은 작동하지만 `/chat` 탭에서는 해당 기능을 사용하려면 WSL2를 사용하라는 배너가 표시됩니다.

브라우저 탭을 닫으면 서버에서 PTY가 깔끔하게 회수됩니다. 다시 열면 새로운 세션이 생성됩니다.

### 설정 \{#config}

`config.yaml`용 폼 기반 편집기입니다. 150개 이상의 모든 구성 필드는 `DEFAULT_CONFIG`에서 자동으로 검색되며 탭으로 구분된 카테고리로 정리됩니다:

- **모델** — 기본 모델, 제공자, 기본 URL, 추론 설정
- **터미널** — 백엔드(로컬/도커/SSH/모달), 타임아웃, 셸 환경 설정
- **디스플레이** — 스킨, 도구 진행, 재개 표시, 스피너 설정
- **에이전트** — 최대 반복 횟수, 게이트웨이 시간 초과, 서비스 등급
- **위임** — 하위 대리인의 제한, 추론 노력
- **메모리** — 제공자 선택, 컨텍스트 주입 설정
- **승인** — 위험한 명령 승인 모드 (ask/yolo/deny)
- 그리고 더 — config.yaml의 모든 섹션에는 해당하는 폼 필드가 있습니다

알려진 유효 값이 있는 필드(터미널 백엔드, 스킨, 승인 모드 등)는 드롭다운으로 렌더링됩니다. 불리언 값은 토글로 렌더링됩니다. 그 외의 모든 것은 텍스트 입력으로 렌더링됩니다.

**동작:**

- **저장** — `config.yaml`에 변경 사항을 즉시 기록합니다
- **기본값으로 재설정** — 모든 필드를 기본값으로 되돌립니다 (저장하려면 '저장'을 클릭해야 합니다)
- **내보내기** — 현재 설정을 JSON으로 다운로드합니다
- **가져오기** — 현재 값을 대체하기 위해 JSON 구성 파일을 업로드합니다

:::tip
구성 변경 사항은 다음 에이전트 세션 또는 게이트웨이 재시작 시 적용됩니다. 웹 대시보드 편집은 `hermes config set`과 게이트웨이가 읽는 동일한 `config.yaml` 파일을 수정합니다.

:::
### API 키 \{#api-keys}

API 키와 자격 증명이 저장된 `.env` 파일을 관리하세요. 키는 카테고리별로 그룹화되어 있습니다:

- **LLM 제공업체** — OpenRouter, Anthropic, OpenAI, DeepSeek 등.
- **도구 API 키** — Browserbase, Firecrawl, Tavily, ElevenLabs 등
- **메시징 플랫폼** — 텔레그램, 디스코드, 슬랙 봇 토큰 등.
- **에이전트 설정** — `API_SERVER_ENABLED`와 같은 비밀이 아닌 환경 변수

각 키는 다음을 보여줍니다:
- 현재 설정되어 있는지 여부(값의 일부가 가려진 미리보기와 함께)
- 그것이 무엇을 위한 것인지에 대한 설명
- 공급자의 가입/키 페이지로 가는 링크
- 값을 설정하거나 업데이트할 수 있는 입력 필드
- 삭제 버튼으로 제거하기

고급/드물게 사용되는 키는 기본적으로 토글 뒤에 숨겨져 있습니다.

### 세션 \{#sessions}

모든 에이전트 세션을 탐색하고 확인하세요. 각 행에는 세션 제목, 소스 플랫폼 아이콘(CLI, Telegram, Discord, Slack, cron), 모델 이름, 메시지 수, 도구 호출 수, 마지막 활동 시간 등이 표시됩니다. 실시간 세션은 깜박이는 배지로 표시됩니다.

- **검색** — FTS5를 사용하여 모든 메시지 내용을 전체 텍스트 검색합니다. 결과는 하이라이트된 스니펫을 표시하며, 확장 시 첫 번째 일치하는 메시지로 자동 스크롤됩니다.
- **확장** — 세션을 클릭하여 전체 메시지 기록을 불러옵니다. 메시지는 역할(사용자, 어시스턴트, 시스템, 도구)에 따라 색상으로 구분되며, 문법 강조가 적용된 Markdown으로 표시됩니다.
- **도구 호출** — 도구 호출이 포함된 보조 메시지는 함수 이름과 JSON 인수가 있는 접이식 블록을 보여줍니다.
- **삭제** — 휴지통 아이콘을 사용하여 세션과 해당 메시지 기록을 제거합니다.

### 로그 \{#logs}

필터링 및 실시간 추적 기능으로 에이전트, 게이트웨이 및 오류 로그 파일을 확인하세요.

- **파일** — `agent`, `errors`, `gateway` 로그 파일 간 전환
- **레벨** — 로그 레벨로 필터: ALL, DEBUG, INFO, WARNING, 또는 ERROR
- **구성요소** — 소스 구성요소별 필터: 전체, 게이트웨이, 에이전트, 도구, CLI, 또는 크론
- **라인** — 표시할 라인 수 선택 (50, 100, 200, 또는 500)
- **자동 새로고침** — 5초마다 새로운 로그 라인을 가져오는 라이브 테일링을 전환합니다
- **색상 구분** — 로그 라인은 심각도에 따라 색이 지정됩니다 (오류는 빨강, 경고는 노랑, 디버그는 흐리게)

### 분석 \{#analytics}

세션 기록에서 계산된 사용량 및 비용 분석입니다. 다음을 보려면 기간(7, 30 또는 90일)을 선택하세요:

- **요약 카드** — 전체 토큰(입력/출력), 캐시 적중 비율, 총 추정 또는 실제 비용, 일일 평균과 함께한 총 세션 수
- **일일 토큰 차트** — 일별 입력 및 출력 토큰 사용량을 표시하는 누적 막대 차트로, 마우스를 올리면 세부 내역과 비용이 표시됩니다.
- **일일 세부 내역 표** — 날짜, 세션 수, 입력 토큰 수, 출력 토큰 수, 캐시 적중률, 일일 비용
- **모델별 세부 내역** — 사용된 각 모델, 세션 수, 토큰 사용량 및 추정 비용을 보여주는 표

### 크론 \{#cron}

에이전트 프롬프트를 정기 일정에 따라 실행하는 예약된 크론 작업을 생성하고 관리합니다.

- **생성** — 이름(선택 사항), 프롬프트, 크론 표현식(예: `0 9 * * *`), 및 전달 대상(로컬, 텔레그램, 디스코드, 슬랙 또는 이메일)을 입력하세요
- **작업 목록** — 각 작업은 이름, 프롬프트 미리보기, 스케줄 표현식, 상태 배지(활성/일시중지/오류), 전달 대상, 마지막 실행 시간, 다음 실행 시간을 표시합니다
- **일시 중지 / 재개** — 작업을 활성 상태와 일시 중지 상태 사이로 전환
- **지금 트리거** — 정상 일정 외에 작업을 즉시 실행
- **삭제** — 크론 작업을 영구적으로 제거

### 기술 \{#skills}

기술과 도구 세트를 찾아보고, 검색하며, 전환하세요. 기술은 `~/.hermes/skills/`에서 불러와지며 카테고리별로 그룹화됩니다.

- **검색** — 이름, 설명 또는 카테고리로 기술과 도구 세트를 필터링
- **카테고리 필터** — 목록을 좁히려면 카테고리 버튼을 클릭하세요 (예: MLOps, MCP, 레드 팀, AI)
- **토글** — 스위치로 개별 스킬을 활성화하거나 비활성화합니다. 변경 사항은 다음 세션에 적용됩니다.
- **도구 세트** — 별도의 섹션에서 내장 도구 세트(파일 작업, 웹 브라우징 등)의 활성/비활성 상태, 설치 요구 사항, 포함된 도구 목록을 보여줍니다

:::warning[Security]
웹 대시보드는 API 키와 비밀을 포함하는 `.env` 파일을 읽고 씁니다. 기본적으로 `127.0.0.1`에 바인딩되며 — 로컬 머신에서만 접근할 수 있습니다. `0.0.0.0`에 바인딩하면 네트워크상의 누구나 자격 증명을 보고 수정할 수 있습니다. 대시보드 자체에는 인증 기능이 없습니다.

:::
## `/reload` 슬래시 명령 \{#reload-slash-command}

대시보드 PR은 또한 인터랙티브 CLI에 `/reload` 슬래시 명령을 추가합니다. 웹 대시보드를 통해(API 키를 변경하거나 `.env`를 직접 편집한 후) 활성 CLI 세션에서 `/reload`를 사용하여 재시작 없이 변경 사항을 적용하세요:

You → /reload Reloaded.env (3 var(s) updated)

이것은 `~/.hermes/.env`를 실행 중인 프로세스의 환경으로 다시 읽어들입니다. 대시보드를 통해 새 공급자 키를 추가하고 즉시 사용하고 싶을 때 유용합니다.

## REST API \{#rest-api}

웹 대시보드는 프론트엔드가 사용하는 REST API를 제공합니다. 또한 자동화를 위해 이러한 엔드포인트를 직접 호출할 수도 있습니다:

### GET /api/status \{#get-apistatus}

에이전트 버전, 게이트웨이 상태, 플랫폼 상태 및 활성 세션 수를 반환합니다.

### GET /api/sessions \{#get-apisessions}

메타데이터(모델, 토큰 수, 타임스탬프, 미리보기)와 함께 최근 세션 20개를 반환합니다.

### GET /api/config \{#get-apiconfig}

현재 `config.yaml` 내용을 JSON으로 반환합니다.

### GET /api/config/defaults \{#get-apiconfigdefaults}

기본 구성 값을 반환합니다.

### GET /api/config/schema \{#get-apiconfigschema}

각 구성 필드의 스키마를 반환합니다 — 유형, 설명, 카테고리, 적용 가능한 경우 선택 옵션 포함. 프론트엔드는 이를 사용하여 각 필드에 적합한 입력 위젯을 렌더링합니다.

### PUT /api/config \{#put-apiconfig}

새 구성을 저장합니다. 본문: `{"config": {...}}`.

### GET /api/env \{#get-apienv}

설정/해제 상태, 마스킹된 값, 설명 및 범주와 함께 알려진 모든 환경 변수를 반환합니다.

### PUT /api/env \{#put-apienv}

환경 변수를 설정합니다. 본문: `{"key": "VAR_NAME", "value": "secret"}`.

### 삭제 /api/env \{#delete-apienv}

환경 변수를 제거합니다. 본문: `{"key": "VAR_NAME"}`.

### GET /api/sessions/{session_id} \{#get-apisessionssessionid}

단일 세션의 메타데이터를 반환합니다.

### GET /api/sessions/{session_id}/messages \{#get-apisessionssessionidmessages}

세션에 대한 전체 메시지 기록을 반환하며, 도구 호출과 타임스탬프를 포함합니다.

### GET /api/sessions/search \{#get-apisessionssearch}

메시지 내용 전체에 대한 전체 텍스트 검색. 쿼리 매개변수: `q`. 하이라이트된 스니펫과 함께 일치하는 세션 ID를 반환합니다.

### DELETE /api/sessions/{session_id} \{#delete-apisessionssessionid}

세션과 해당 메시지 기록을 삭제합니다.

### GET /api/logs \{#get-apilogs}

로그 라인을 반환합니다. 쿼리 매개변수: `file` (agent/errors/gateway), `lines` (count), `level`, `component`.

### GET /api/analytics/usage \{#get-apianalyticsusage}

토큰 사용량, 비용 및 세션 분석을 반환합니다. 쿼리 파라미터: `days` (기본값 30). 응답에는 일별 분석과 모델별 집계가 포함됩니다.

### GET /api/cron/jobs \{#get-apicronjobs}

상태, 일정 및 실행 기록과 함께 구성된 모든 크론 작업을 반환합니다.

### POST /api/cron/jobs \{#post-apicronjobs}

새로운 크론 작업을 생성합니다. 본문: `{"prompt": "...", "schedule": "0 9 * * *", "name": "...", "deliver": "local"}`.

### POST /api/cron/jobs/{job_id}/pause \{#post-apicronjobsjobidpause}

크론 작업을 일시 중지합니다.

### POST /api/cron/jobs/{job_id}/resume \{#post-apicronjobsjobidresume}

일시 중지된 크론 작업을 다시 시작합니다.

### POST /api/cron/jobs/{job_id}/trigger \{#post-apicronjobsjobidtrigger}

즉시 계획된 일정 외에서 크론 작업을 실행합니다.

### DELETE /api/cron/jobs/{job_id} \{#delete-apicronjobsjobid}

크론 작업을 삭제합니다.

### GET /api/skills \{#get-apiskills}

이름, 설명, 카테고리 및 활성화 상태와 함께 모든 기술을 반환합니다.

### PUT /api/skills/toggle \{#put-apiskillstoggle}

스킬을 활성화하거나 비활성화합니다. 내용: `{"name": "skill-name", "enabled": true}`.

### GET /api/tools/toolsets \{#get-apitoolstoolsets}

레이블, 설명, 도구 목록 및 활성/구성 상태와 함께 모든 도구 세트를 반환합니다.

## CORS \{#cors}

웹 서버는 CORS를 로컬호스트 출처로만 제한합니다:

- `http://localhost:9119` / `http://127.0.0.1:9119` (생산)
- `http://localhost:3000` / `http://127.0.0.1:3000`
- `http://localhost:5173` / `http://127.0.0.1:5173` (Vite 개발 서버)

서버를 사용자 지정 포트에서 실행하면 해당 출처가 자동으로 추가됩니다.

## 개발 \{#development}

웹 대시보드 프론트엔드에 기여하고 있다면:

```bash
# Terminal 1: start the backend API
hermes dashboard --no-open

# Terminal 2: start the Vite dev server with HMR
cd web/
npm install
npm run dev

Vite 개발 서버 http://localhost:5173는 /api 요청을 FastAPI 백엔드 http://127.0.0.1:9119로 프록시합니다.

프론트엔드는 React 19, TypeScript, Tailwind CSS v4, 그리고 shadcn/ui 스타일 컴포넌트로 구축되었습니다. 프로덕션 빌드는 hermes_cli/web_dist/로 출력되며, FastAPI 서버가 이를 정적 SPA로 제공합니다.

업데이트 시 자동 빌드

hermes update를 실행하면, npm이 사용 가능할 경우 웹 프론트엔드가 자동으로 재빌드됩니다. 이렇게 하면 대시보드가 코드 업데이트와 동기화 상태를 유지할 수 있습니다. 만약 npm가 설치되어 있지 않으면, 업데이트가 프론트엔드 빌드를 건너뛰고 첫 실행 시 hermes dashboard가 이를 빌드합니다.

테마 및 플러그인

대시보드는 여섯 가지 기본 제공 테마와 함께 제공되며, 사용자 정의 테마, 플러그인 탭, 백엔드 API 경로로 확장할 수 있습니다 — 모두 바로 사용 가능하며, 리포지토리 복제는 필요하지 않습니다.

헤더 바에서 테마를 실시간으로 전환하세요 — 언어 전환기 옆의 팔레트 아이콘을 클릭하세요. 선택 사항은 config.yaml 아래의 dashboard.theme에 유지되며 페이지 로드 시 복원됩니다.

내장 테마:

테마	캐릭터
헤르메스 틸 (default)	다크 틸 + 크림, 시스템 폰트, 편안한 간격
에르메스 틸 (대형) (default-large)	기본과 같지만 글자 크기는 18px이고 간격이 더 넓음
자정 (midnight)	짙은 청보라색, 인터 + 제트브레인스 모노
엠버 (ember)	따뜻한 크림슨 + 청동, 스펙트럴 세리프 + IBM 플렉스 모노
모노 (mono)	그레이스케일, IBM 플렉스, 컴팩트
사이버펑크 (cyberpunk)	검은색 바탕에 네온 그린, 쉐어 테크 모노
로제 (rose)	핑크 + 아이보리, 프라우스 세리프, 넓은

자신만의 테마를 만들고, 플러그인 탭을 추가하며, 셸 슬롯에 주입하거나 플러그인 전용 REST 엔드포인트를 노출하려면 **대시보드 확장하기**를 참고하세요 — 완전한 가이드는 다음 내용을 다룹니다:

• 테마 YAML 스키마 — 팔레트, 타이포그래피, 레이아웃, 자산, 컴포넌트 스타일, 색상 덮어쓰기, 사용자 정의 CSS
• 레이아웃 변형 — standard, cockpit, tiled
• 플러그인 매니페스트, SDK, 셸 슬롯, 페이지 범위 슬롯(빌트인 페이지를 덮어쓰지 않고 위젯 주입), 백엔드 FastAPI 라우트
• 전체 결합 테마 + 플러그인 연습(스트라이크 프리덤 조종석 데모)
• 탐색, 다시 로드, 문제 해결