hermes-webui

KO | EN

gitlite — search

#javascript #python #hacktoberfest #golang #android #machine-learning #docker #macos #java #nodejs #kubernetes #vue #security #ios

(★ 17,394)

Hermes WebUI: 웹이나 스마트폰에서 Hermes Agent를 사용하는 가장 좋은 방법!

hermes-webui 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Hermes Web UI
[Hermes Agent](https://hermes-agent.nousresearch.com/)는 서버에서 실행되며 터미널이나 메신저 앱을 통해 액세스할 수 있는 정교한 자율형 에이전트입니다. 학습한 내용을 기억하고 실행 시간이 길어질수록 더 유능해집니다.
Hermes WebUI는 브라우저에서 [Hermes Agent](https://hermes-agent.nousresearch.com/)를 사용할 수 있도록 지원하는 가벼운 다크 모드 웹 앱 인터페이스입니다.
CLI 환경과 완벽하게 호환되므로 터미널에서 할 수 있는 모든 것을 이 UI에서도 할 수 있습니다. 빌드 단계, 프레임워크, 번들러가 필요 없습니다. 오직 Python과 바닐라 JS로만 이루어져 있습니다.
레이아웃: 3단 패널 구조. 왼쪽 사이드바에는 세션과 네비게이션, 가운데에는 채팅,
오른쪽에는 워크스페이스 파일 브라우저가 위치합니다. 모델, 프로필, 워크스페이스 컨트롤은 메시지를 작성하는 동안 항상 표시되는 **composer footer**에 있습니다.
원형 컨텍스트 링을 통해 토큰 사용량을 한눈에 확인할 수 있습니다. 모든 설정과 세션 도구는 **Hermes Control Center**(사이드바 하단의 런처)에 있습니다.
모든 기기에서 네이티브로 액세스할 수 있도록 Hermes를 설정하세요:
![image](https://github.com/user-attachments/assets/9a72cdf3-a5b4-45ed-a836-a715ce46287e)

|  |  |
| --- | --- |
| 전체 프로필을 지원하는 라이트 모드  전체 프로필을 지원하는 라이트 모드 | 설정 사용자 지정, 비밀번호 구성  설정 사용자 지정, 비밀번호 구성 |

|  |  |
| --- | --- |
| 인라인 미리보기가 지원되는 워크스페이스 파일 브라우저  인라인 미리보기가 지원되는 워크스페이스 파일 브라우저 | 세션 프로젝트, 태그, 툴 콜 카드  세션 프로젝트, 태그, 툴 콜 카드 |

이 기능을 사용하면 Hermes 설정에서 SSH 터널을 통해 안전하게 접속할 수 있는 **편리한 웹 UI를 통해 Hermes CLI와 거의 1:1 수준의 동등한 기능**을 누릴 수 있습니다. 명령어 한 번으로 이를 시작하고, 명령어 한 번으로 SSH 터널을 연결하여 컴퓨터에서 접속할 수 있습니다. 웹 UI의 모든 부분은 추가 설정 없이 기존의 Hermes 에이전트와 기존 모델을 그대로 사용합니다.
---
## 목차
[![image](https://github.com/user-attachments/assets/7e9544a7-ba47-4fc7-8142-1d9d16b17065)
](https://get-hermes.ai/setup/)
- [왜 Hermes인가](#why-hermes) — Hermes가 무엇이고 어떻게 비교되는지
- [빠른 시작](#quick-start) — 복제(clone) + `bootstrap.py` / `start.sh` / `ctl.sh`
- [기능](#features) — 채팅, 세션, 작업 공간(workspace), 음성, 프로필, 보안, 테마, 패널, 모바일
- [설정 및 액세스](#configuration--access) — 자동 검색, 오버라이드, 원격/Tailscale/휴대폰, 수동 실행
- [Nix 플래이크/모듈](#nix-flake-and-nixos-module) — 선언적 설치 및 서비스
- [Docker](#docker) — 단일 및 다중 컨테이너 배포
- [테스트 실행](#running-tests)
- [아키텍처](#architecture) — 백엔드/프론트엔드 레이아웃, 상태 디렉터리
- [문서](#docs) — 전체 문서 색인
- [기여자](#contributors)
---
## 왜 Hermes인가
대부분의 AI 도구는 세션마다 초기화됩니다. 사용자가 누구인지, 무엇을 작업했는지, 프로젝트가 어떤 규칙을 따르는지 알지 못합니다. 매번 똑같은 설명을 반복해야 하죠.
Hermes는 세션 간에 컨텍스트를 유지하고, 오프라인 상태일 때도 예약된 작업을 실행하며, 실행 시간이 길어질수록 사용자의 환경에 대해 더 똑똑해집니다. 기존의 Hermes 에이전트 설정과 모델을 그대로 사용하며, 시작하는 데 별도의 추가 설정이 필요 없습니다.
다른 에이전트 도구들과 차별화되는 점:
- \*\*영구 메모리\*\* — 사용자 프로필, 에이전트 노트, 그리고 재사용 가능한 절차를 저장하는 스킬 시스템; Hermes는 사용자의 환경을 학습하고 다시 학습할 필요가 없습니다.
- \*\*자체 호스팅 스케줄링\*\* — 오프라인 상태일 때 실행되어 텔레그램(Telegram), 디스코드(Discord), 슬랙(Slack), 시그널(Signal), 이메일 등으로 결과를 전달하는 크론(cron) 작업
- \*\*10개 이상의 메시징 플랫폼\*\* — 터미널에서 사용할 수 있는 동일한 에이전트를 휴대폰에서도 접근 가능
- \*\*자기 개선형 스킬\*\* — Hermes가 경험을 바탕으로 자신의 스킬을 자동으로 작성하고 저장; 둘러볼 마켓플레이스나 설치할 플러그인이 필요 없음
- \*\*프로바이더 독립적\*\* — OpenAI, Anthropic, Google, DeepSeek, OpenRouter 등 지원
- \*\*다른 에이전트 오케스트레이션\*\* — 복잡한 코딩 작업을 위해 Claude Code나 Codex를 생성하고 그 결과를 자신의 메모리로 가져옴
- \*\*자체 호스팅\*\* — 내 대화, 내 메모리, 내 하드웨어
\*\*타 제품과의 비교\*\* \*(생태계가 활발히 변화 중입니다. 전체 분석은 [docs/why-hermes.md](docs/why-hermes.md)를 참조하세요)\*:
| | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
|---|---|---|---|---|---|
| 영구 메모리 (자동) | 예 | 부분적† | 부분적 | 부분적 | 예 |
| 예약된 작업 (자체 호스팅) | 예 | 아니오‡ | 아니오 | 아니오 | 예 |
| 메시징 앱 액세스 | 예 (15개 이상 플랫폼) | 부분적 (텔레그램/디스코드 미리보기) | 아니오 | 아니오 | 예 (10개 이상) |
| 웹 UI (자체 호스팅) | 대시보드 전용 | 아니오 | 아니오 | 예 | 예 |
| 자기 개선형 스킬 | 부분적 | 아니오 | 아니오 | 아니오 | 예 |
| Python / ML 생태계 | 아니오 (Node.js) | 아니오 | 아니오 | 아니오 | 예 |
| 프로바이더 독립적 | 예 | 아니오 (Claude 전용) | 예 | 예 | 예 |
| 오픈 소스 | 예 (MIT) | 아니오 | 예 | 예 | 예 |
† Claude Code에는 CLAUDE.md / MEMORY.md 프로젝트 컨텍스트와 롤링 자동 메모리가 있지만, 완전한 자동 세션 간 리콜 기능은 없습니다.
‡ Claude Code에는 클라우드 관리형 스케줄링(Anthropic 인프라)과 세션 범위의 `/loop`가 있지만, 자체 호스팅 크론은 없습니다.
\*\*가장 강력한 경쟁자는 OpenClaw입니다\*\* — 두 제품 모두 메모리, 크론, 메시징 기능을 갖춘 상시 가동형 자체 호스팅 오픈 소스 에이전트입니다. 주요 차이점은 다음과 같습니다. Hermes는 핵심 동작으로 자신의 스킬을 자동으로 작성하고 저장합니다(OpenClaw의 스킬 시스템은 커뮤니티 마켓플레이스를 중심으로 함). 또한 Hermes가 업데이트 전반에 걸쳐 더 안정적입니다(OpenClaw은 릴리스 회귀가 문서화되어 있고 ClawHub에는 악성 스킬과 관련된 보안 사고가 있었음).

; 그리고 Hermes는 Python 생태계에서 네이티브로 실행됩니다. 전체 비교 분석은 [docs/why-hermes.md](docs/why-hermes.md)를 참조하세요.
---
## 빠른 시작
저장소 부트스트랩을 실행합니다:
```bash
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py
```
또는 셸 런처를 계속 사용할 수 있습니다:
```bash
./start.sh
```
셀프 호스팅 VM이나 홈랩 설치의 경우, `ctl.sh`는 `fuser`나 `pkill` 없이 일반적인 데몬 수명 주기 명령을 감싸서 제공합니다:
```bash
./ctl.sh start # 백그라운드 데몬, PID는 ~/.hermes/webui.pid에 저장됨
./ctl.sh status # PID, 업타임, 바인딩된 호스트/포트, 로그 경로, /health
./ctl.sh logs --lines 100 # ~/.hermes/webui.log 실시간 출력
./ctl.sh restart
./ctl.sh stop
```
`ctl.sh start`는 데몬 래퍼 뒤에서 포그라운드/브라우저 없음 모드로 부트스트랩을 실행하고, `~/.hermes/webui.log`에 로그를 기록하며, `.env` 및 `HERMES\_WEBUI\_HOST=0.0.0.0 ./ctl.sh start`와 같은 인라인 오버라이드를 따릅니다.
> \*\*서버 중지.\*\* `ctl.sh start`만 PID 파일(`~/.hermes/webui.pid`)을 생성하므로 각 실행 방법마다 고유한 중지 경로가 있습니다:
>
> | 실행 방법 | 중지 방법 |
> |---|---|
> | `python3 bootstrap.py` | 터미널에서 \*\*Ctrl-C\*\* (포그라운드에서 실행됨) |
> | `./ctl.sh start` | `./ctl.sh stop` (SIGTERM 전송 후 대기, 그 다음 SIGKILL 전송) |
> | 분리된 `bootstrap.py` (`--foreground` 없음) 또는 `./start.sh` | `lsof -i :8787` (또는 `ss -tlnp`)을 통해 PID를 찾아 `kill` 실행 |
>
> `./ctl.sh stop`은 `bootstrap.py`나 `start.sh`로 직접 실행된 서버를 중지할 수 없습니다. 자신이 직접 시작한 프로세스만 관리합니다.
> \*\*기본 채팅 실행 방식.\*\* WebUI는 Hermes 에이전트를 프로세스 내에서 실행하며, 사용자의 `HERMES\_HOME` 설정을 직접 읽습니다. 채팅을 실행하기 위해 외부 Hermes/agent OpenAI 호환 API 서버에 연결하지 않습니다. `HERMES\_API\_URL`은 작업(Tasks)/크론(cron) 상태 프로브에서만 읽으며 채팅을 라우팅하지 않습니다.
>
> 외부 엔드포인트를 실행하는 경우 두 가지 옵션이 있습니다:
>
> 1. \*\*해당 모델을 채팅 제공자로 사용\*\* (현재 지원됨): \*\*설정 → 제공자(Settings → Providers)\*\*에서 `base\_url = http://127.0.0.1:8642/v1` 및 베어러 토큰을 사용하여 커스텀 OpenAI 호환 제공자로 추가합니다.
> 2. \*\*Hermes Gateway API 서버를 통해 채팅 라우팅\*\* (현재 `HERMES\_WEBUI\_CHAT\_BACKEND=gateway`를 통해 지원됨): [`docs/advanced-chat-setup.md`](docs/advanced-chat-setup.md)를 참조하세요.
> 전체 에이전트 루프 위임은 아직 출시되지 않았으며, [#1925](https://github.com/nesquena/hermes-webui/issues/1925)에서 추적 중입니다.
### 고급: 동적 리콜 프리필 및 Gateway 기반 채팅
브라우저 턴에 동적 \*\*세션 리콜 프리필(session-recall prefill)\*\* 연결(Joplin/Obsidian/Notion/llm-wiki 라우터), 그리고 실행 중인 \*\*Hermes Gateway\*\*를 통한 브라우저 채팅 라우팅이라는 두 가지 선택적 셀프 호스팅 배포 기능은 [`docs/advanced-chat-setup.md`](docs/advanced-chat-setup.md)에 문서화되어 있습니다. 대부분의 사용자는 이 기능들이 필요하지 않습니다.
부트스트랩이 수행하는 작업:
1. Hermes Agent를 감지하고, 없으면 공식 설치 프로그램 (`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash`)을 시도합니다.
2. WebUI 종속성이 포함된 Python 환경을 찾거나 생성합니다.
3. 웹 서버를 시작하고 `/health`를 기다립니다.
4. `--no-browser`를 전달하지 않은 경우 브라우저를 엽니다.
5. WebUI 내부의 첫 실행 온보딩 마법사로 진입시킵니다.
> 네이티브 Windows는 아직 이 부트스트랩을 지원하지 않습니다. Linux, macOS 또는 WSL2를 사용하세요.
> Windows / WSL 로그인 시 자동 시작에 대해서는 [`docs/wsl-autostart.md`](docs/wsl-autostart.md)를 참조하세요.
커뮤니티에서 유지 관리하는 네이티브 Windows 설정은 [@markwang2658/hermes-windows-native-guide](https://github.com/markwang2658/hermes-windows-native-guide)에 문서화되어 있습니다 (컴패니언 설정 저장소: [@markwang2658/hermes-windows-native](https://github.com/markwang2658/hermes-windows-native)). [#1952](https://github.com/nesquena/hermes-webui/issues/1952)에 보고된 커뮤니티 노트:
- \*\*메모리:\*\* 커뮤니티 측정 결과 네이티브 환경은 약 330MB, WSL2+Docker 환경은 약 1080MB (설정에 따라 다름).
- \*\*작동 기능:\*\* 채팅, 워크스페이스 브라우저, 세션 관리, 모든 테마.
-

- \*\*알려된 제한 사항:\*\* 일부 POSIX 스타일 파일 경로가 워크스페이스 브라우저에 나타날 수 있으며, bash를 가정하는 에이전트 도구는 네이티브로 작동하지 않을 수 있습니다.
- \*\*네이티브 Windows 설정:\*\* Python 3.11+을 설치한 후, PowerShell의 `hermes-agent` 루트 디렉토리에서 다음을 실행합니다: `python -m venv venv` → `pip install -r requirements.txt` → `pwsh .\start.ps1` (`venv\Scripts\python.exe`를 자동으로 감지합니다).
- \*\*WSL2와의 관계:\*\* 필수 조건은 아닙니다. WSL2로 빌드된 venv(`venv/bin/python`, ELF)는 네이티브 Windows Python에서 실행할 수 없으므로 위에서 설명한 네이티브 설정을 사용하세요. 전체 `bootstrap.py`와 Linux 런타임을 원한다면 병렬 설치 용도로 WSL2를 계속 유용하게 사용할 수 있습니다.
설치 후에도 공급자(provider) 설정이 완료되지 않은 경우, 브라우저에서 전체 CLI 설정을 수동으로 복제하려고 시도하는 대신 온보딩 마법사가 `hermes model`을 통해 설정을 완료하도록 안내해 줍니다.
마법사의 단계별 안내, 공급자 선택, 로컬 모델 서버 Base URL, 그리고 안전한 재실행 방법에 대해서는 [`docs/onboarding.md`](docs/onboarding.md)를 참조하세요.
AI 어시스턴트가 설치, 재설치, 부트스트랩, 공급자 설정 또는 첫 실행 지원을 돕고 있는 경우, 명령어 실행이나 로그 검사 전에 [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md)를 먼저 읽도록 하세요.
---
## 기능 (Features)
### 채팅 및 에이전트 (Chat and agent)
- SSE를 통한 스트리밍 응답 (토큰이 생성되는 대로 표시됨)
- 다중 공급자 모델 지원 -- 모든 Hermes API 공급자(OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI) 지원; 구성된 키를 기반으로 동적 모델 드롭다운 채워짐
- 메시지 처리 중에도 새 메시지 전송 가능 -- 자동으로 대기열에 추가됨
- 과거 사용자 메시지를 인라인으로 편집하고 해당 지점부터 재생성
- 클릭 한 번으로 마지막 어시스턴트 응답 재시도
- 컴포저 하단에서 실행 중인 작업 즉시 취소 (전송 버튼 옆의 중지 버튼)
- 인라인 도구 호출 카드 -- 각 카드는 도구 이름, 인자, 결과 스니펫을 표시함; 다중 도구 턴을 위한 전체 확장/축소 토글 제공
- 서브에이전트 위임 카드 -- 고유한 아이콘과 들여쓰기된 테두리로 하위 에이전트 활동 표시
- 인라인 Mermaid 다이어그램 렌더링 (순서도, 시퀀스 다이어그램, 간트 차트)
- 생각/추론 과정 표시 -- Claude 확장 사고 및 o3 추론 블록을 위한 접을 수 있는 골드 테마 카드
- 위험한 쉘 명령어를 위한 승인 카드 (한 번 허용 / 세션 동안 허용 / 항상 허용 / 거부)
- 네트워크 끊김 시 SSE 자동 재연결 (SSH 터널 복원력)
- 파일 첨부 파일은 페이지 새로고침 후에도 유지되며 기본적으로 활성 워크스페이스 외부에 저장됨 (`~/.hermes/webui/attachments//`, 또는 설정된 경우 `HERMES\_WEBUI\_ATTACHMENT\_DIR//`)
- 메시지 타임스탬프 (각 메시지 옆에 HH:MM 표시, 호버 시 전체 날짜 표시)
- "복사 완료!" 피드백이 포함된 코드 블록 복사 버튼
- Prism.js를 통한 구문 강조 (Python, JS, bash, JSON, SQL 등)
- AI 응답 내 안전한 HTML 렌더링 (볼드, 이탤릭, 마크다운으로 변환된 코드)
- 긴 응답 중 더 부드러운 렌더링을 위해 rAF로 조절되는 토큰 스트리밍
- 컴포저 하단의 컨텍스트 사용량 표시기 -- 토큰 수, 비용, 채움 바 (모델 인식형)
### 세션 (Sessions)
- 생성, 이름 변경, 복제, 삭제, 제목 및 메시지 내용으로 검색
- 세션별 `⋯` 드롭다운을 통한 세션 작업 — 고정, 프로젝트로 이동, 아카이브, 복제, 삭제
- 세션을 사이드바 상단에 고정/별표 표시 (골드 표시기)
- 세션 아카이브 (삭제하지 않고 숨기기, 표시 여부 토글 가능)
- 세션 프로젝트 -- 세션을 정리하기 위한 색상이 지정된 이름별 그룹
- 세션 태그 -- 제목에 `#tag`를 추가하여 색상 칩 생성 및 클릭하여 필터링
- 사이드바에서 오늘 / 어제 / 이전으로 그룹화 (접을 수 있는 날짜 그룹)
- Markdown 대화 기록으로 다운로드, 전체 JSON 내보내기, 또는 JSON에서 가져오기
- 제어 센터에서 활성 대화에 대한 공개 읽기 전용 공유 링크 생성; 공유된 페이지에는 워크스페이스, 프로필, 라이브 제어 기능이 제외된 정제된 대화 기록 스냅샷이 표시됨
- 페이지 새로고침 및 SSH 터널 재연결 후에도 세션 유지
- 브라우저 탭 제목에 활성 세션 이름 반영
- CLI 세션 브리지 -- hermes-agent의 SQLite 저장소에 있는 CLI 세션이 사이드바에 표시됨

old "cli" 배지; 클릭하여 전체 기록과 함께 가져오고 정상적으로 회신
- 토큰/비용 표시 -- 대화별로 입력 토큰, 출력 토큰, 예상 비용 표시 (설정 또는 `/usage` 명령어에서 토큰 토글 가능)
### Workspace 파일 브라우저
- 확장/축소 기능이 있는 디렉토리 트리 (한 번 클릭하여 토글, 두 번 클릭하여 이동)
- 클릭 가능한 경로 세그먼트가 있는 브레드크럼 탐색
- 텍스트, 코드, Markdown(렌더링됨), 이미지 인라인 미리보기
- `workspace://path/to/file`을 사용하는 채팅 링크는 우측 미리보기 창에서 파일을 엽니다.
- 파일 편집, 생성, 삭제, 이름 변경 및 폴더 생성
- 바이너리 파일 다운로드 (서버에서 자동 감지)
- 디렉토리 이동 시 파일 미리보기 자동 닫힘 (저장되지 않은 편집 보호 기능 포함)
- Git 감지 -- workspace 헤더에 브랜치 이름 및 수정된 파일 수 배지 표시
- 우측 패널은 드래그하여 크기 조절 가능
- 구문 강조 표시된 코드 미리보기 (Prism.js)
### 음성 입력
- 입력창의 마이크 버튼 (Web Speech API)
- 탭하여 녹음, 다시 탭하거나 전송하여 중지
- 실시간 임시 전사(transcription)가 텍스트 영역에 표시됨
- 약 2초 동안 침묵이 유지되면 자동 중지
- 기존 텍스트 영역 내용에 추가됨 (대체되지 않음)
- 브라우저가 Web Speech API를 지원하지 않는 경우 숨겨짐 (Chrome, Edge, Safari)
### 프로필
- \*\*composer footer\*\*의 프로필 칩 -- 게이트웨이 상태와 모델 정보가 포함된 모든 프로필을 보여주는 드롭다운
- 게이트웨이 상태 점 (녹색 = 실행 중), 모델 정보, 프로필별 스킬 수
- 프로필 관리 패널 -- 사이드바에서 프로필 생성, 전환 및 삭제
- 생성 시 활성 프로필에서 설정 복제
- 생성 시 선택적 커스텀 엔드포인트 필드 -- 생성 시점에 프로필의 `config.yaml`에 Base URL과 API 키가 기록되므로, 파일을 수동으로 편집하지 않고도 Ollama, LMStudio 및 기타 로컬 엔드포인트를 구성할 수 있습니다.
- 원활한 전환 -- 서버 재시작 없음; 설정, 스킬, 메모리, cron, 모델을 다시 로드함
- 세션별 프로필 추적 (생성 시 활성화되었던 프로필 기록)
### 인증 및 보안
- 선택적 비밀번호 인증 -- 기본적으로 꺼져 있으며 로컬 호스트에서 마찰 없음
- `HERMES\_WEBUI\_PASSWORD` 환경 변수 또는 설정 패널을 통해 활성화
- 설치된 PWA는 WebUI 자체 비밀번호를 사용할 때 가장 잘 작동합니다. 리버스 프록시가 지원되지만, 프록시 기본 인증은 설치된 앱에 필요한 서비스 워커 업데이트 가져오기를 차단하여 업데이트 후 빈 화면 상태로 남겨둘 수 있습니다. 복구 단계는 `docs/troubleshooting.md`를 참조하세요.
- 선택적 패스키/WebAuthn -- 비밀번호로 로그인한 후 설정 -> 시스템에서 등록; 로그인 페이지에는 하나 이상의 패스키가 존재한 후에만 패스키 로그인이 표시됨
- 하나 이상의 패스키를 등록한 후, 설정 -> 시스템에서 비밀번호를 제거하고 패스키 전용 로그인 상태를 유지할 수 있습니다. 비밀번호를 사용하지 않기로 선택할 때까지 비밀번호 인증은 부트스트랩/복구 경로로 유지됩니다. 패스키는 동일 출처(same-origin)이며 WebUI 상태 디렉토리에 로컬로 저장됩니다.
- WebUI 세션을 위한 선택적 네이티브 OIDC 로그인 -- `config.yaml`에서 `webui\_oidc.issuer`, `client\_id`, `allow\_claim`, `allow\_values`를 설정하거나 일치하는 `HERMES\_WEBUI\_OIDC\_\*` 환경 변수를 설정합니다. 네 가지 모두가 제공될 때까지 OIDC는 비활성화 상태로 유지되며, 설정이 부분적인 경우 시작할 때 경고가 출력됩니다.
- 네이티브 OIDC는 프로세스 메모리에 PKCE/상태 nonce 흐름을 저장합니다. 이는 제공되는 단일 프로세스 서버에서 작동하며, 콜백이 동일한 WebUI 인스턴스에 유지되는 로드 밸런서 뒤에서도 작동합니다. 다중 인스턴스 배포에는 세션 친화성(affinity)이 필요합니다. 그렇지 않으면 콜백이 다른 프로세스로 전달되어 상태 유효성 검사에 실패할 수 있습니다.
- 24시간 TTL이 지정된 서명된 HMAC HTTP-only 쿠키
- `/login`의 미니멀한 다크 테마 로그인 페이지
- 모든 응답에 대한 보안 헤더 (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
- 20MB POST 본문 크기 제한
- SRI 무결성 해시가 고정된 CDN 리소스
### 테마
- 외관은 두 가지 축으로 나뉩니다: 테마(`system`, `dark`, `light`) 및 스킨
(`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, `charizard`,
`sienna`, `catppuccin`, `nous`, `geist-contrast` / Geist Contrast)
- 설정 -> 외관(Appearance)을 통해 전환 (i

instant live preview) 또는 `/theme `
- 리로드 시에도 유지됨 (설정 파일의 서버 측 settings.json + 깜빡임 없는 로딩을 위한 localStorage)
- 스킨은 `data-skin`과 CSS 변수를 사용하며, 다크 모드는 `data-theme` 커스텀 테마 축이 아니라 `.dark` 클래스를 통해 해결됨 — [THEMES.md](THEMES.md) 참조
### 설정 및 구성
- \*\*Hermes Control Center\*\* (사이드바 런처 버튼) -- 대화 탭(내보내기/가져오기/지우기), 환경설정 탭(모델, 전송 키, 테마, 언어, 모든 토글), 시스템 탭(버전, 비밀번호)
- 전송 키: Enter (기본값) 또는 Ctrl/Cmd+Enter
- CLI 세션 표시/숨기기 토글 (기본적으로 활성화됨)
- 토큰 사용량 표시 토글 (기본적으로 비활성화됨, `/usage` 명령어로도 가능)
- Control Center는 항상 대화 탭에서 열리며 닫을 때 초기화됨
- 저장되지 않은 변경 사항 보호 -- 저장되지 않은 변경 사항이 있는 상태로 닫을 때 폐기/저장 프롬프트 표시
- Cron 완료 알림 -- 작업 탭 및 세션 사이드바의 활성 프로필에 범위가 지정된 토스트 알림 및 읽지 않은 배지
- 백그라운드 에이전트 오류 알림 -- 활성 상태가 아닌 세션에서 오류가 발생할 때 배너 표시
### 슬래시 명령어
- 입력창에 `/`를 입력하여 자동 완성 드롭다운 표시
- 일반 스킬은 이름이나 설명의 대소문자를 구분하지 않는 키워드와 일치하며, 내장 명령어나 에이전트/플러그인 및 번들 명령어는 접두사 일치를 유지하고 동일한 슬러그의 스킬보다 우선순위가 높음
- 내장 명령어: `/help`, `/clear`, `/compress [focus topic]`, `/compact` (별칭), `/model `, `/workspace `, `/new`, `/usage`, `/theme`
- 방향키로 이동, Tab/Enter로 선택, Escape로 닫기
- 인식되지 않는 명령어는 에이전트로 그대로 전달됨
### 패널
- \*\*Chat\*\* -- 세션 목록, 검색, 고정, 보관, 프로젝트, 새 대화
- \*\*Tasks\*\* -- cron 작업 보기, 생성, 수정, 실행, 일시 중지/재개, 삭제; 실행 기록; 완료 알림
- \*\*Skills\*\* -- 카테고리별 모든 스킬 목록, 검색, 미리보기, 생성/수정/삭제; 연결된 파일 뷰어
- \*\*Memory\*\* -- MEMORY.md 및 USER.md 인라인 보기 및 편집
- \*\*Profiles\*\* -- 에이전트 프로필 생성, 전환, 삭제; 설정 복제
- \*\*Todos\*\* -- 현재 세션의 실시간 작업 목록
- \*\*Spaces\*\* -- 워크스페이스 추가, 이름 변경, 제거; 상단바에서 빠른 전환
### 모바일 반응형
- 햄버거 사이드바 -- 모바일(<640px)에서 슬라이드인 오버레이
- 모바일에서도 사이드바 상단 탭 사용 가능; 채팅 높이를 차지하는 고정 하단 내비게이션 없음
- 오른쪽 가장자 터치 영역은 모든 상호작용 요소에서 최소 44px
- 하단 내비게이션 여백이 없는 스마트폰에서의 전체 높이 채팅/입력창
- 데스크톱 레이아웃은 완전히 유지됨
---
## 설정 및 액세스
`start.sh`는 거의 모든 것을 자동으로 감지합니다. 아래 하위 섹션에서는 자동 감지가 실패할 경우를 위한 조정 방법과 UI에 원격으로 접속하는 방법을 다룹니다.
### start.sh가 자동으로 찾는 항목
| 항목 | 감지 방법 |
|---|---|
| Hermes 에이전트 디렉토리 | `HERMES\_WEBUI\_AGENT\_DIR`, 알려진 체크아웃 경로, `PATH`상의 `hermes` 런처, 그리고 마지막으로 `HERMES\_WEBUI\_PYTHON`이 노출하는 설치된 `run\_agent` 모듈 |
| Python 실행 파일 | 에이전트 venv 우선, 다음으로 이 저장소의 `.venv`, 마지막으로 시스템 `python3` |
| 상태 디렉토리 | `HERMES\_WEBUI\_STATE\_DIR` 환경 변수, 다음으로 `$HERMES\_HOME/webui` (Windows 기본값 `%LOCALAPPDATA%\hermes\webui`, POSIX 기본값 `~/.hermes/webui`) |
| 기본 워크스페이스 | `HERMES\_WEBUI\_DEFAULT\_WORKSPACE` 환경 변수, 다음으로 `~/workspace`, 마지막으로 상태 디렉토리 |
| 포트 | `HERMES\_WEBUI\_PORT` 환경 변수 또는 첫 번째 인자, 기본값 `8787` |
자동 감지가 모든 것을 찾으면 다른 조치는 필요하지 않습니다.
---
### 오버라이드 (자동 감지가 실패한 경우에만 필요)
```bash
export HERMES\_WEBUI\_AGENT\_DIR=/path/to/hermes-agent
export HERMES\_WEBUI\_PYTHON=/path/to/python
export HERMES\_WEBUI\_PORT=9000
export HERMES\_WEBUI\_AUTO\_INSTALL=1 # 에이전트 종속성 자동 설치 활성화 (기본값은 비활성화)
./start.sh
```
또는 인라인으로 실행:
```bash
HERMES\_WEBUI\_AGENT\_DIR=/custom/path ./start.sh 9000
```
환경 변수 전체 목록:
| 변수 | 기본값 | 설명 |
|---|---|---|
| `HERMES\_WEBUI\_AGENT\_DIR` | 자동 감지됨 | Hermes Agent 소스 또는 설치된 모듈 루트 경로 |

| `HERMES\_WEBUI\_PYTHON` | 자동 검색됨 | Python 실행 파일 |
| `HERMES\_WEBUI\_HOST` | `127.0.0.1` | 바인드 주소 (모든 IPv4는 `0.0.0.0`, 모든 IPv6는 `::`, IPv6 루프백은 `::1`) |
| `HERMES\_WEBUI\_PORT` | `8787` | 포트 |
| `HERMES\_WEBUI\_STATE\_DIR` | `$HERMES\_HOME/webui` (Windows 기본값 `%LOCALAPPDATA%\hermes\webui`, POSIX 기본값 `~/.hermes/webui`) | 세션 및 상태가 저장되는 위치입니다. \*\*참고(업그레이드):\*\* 이제 기본값이 `HERMES\_HOME`을 따릅니다. 이전에 `HERMES\_WEBUI\_STATE\_DIR`을 설정하지 \*\*않고\*\* `HERMES\_HOME`을 기본값이 아닌 다른 기본 경로로 재배치한 경우, 이제 WebUI 상태가 기존 플랫폼 기본값인 `~/.hermes/webui` 대신 `$HERMES\_HOME/webui`로 해결됩니다. 기존 위치를 계속 사용하려면 `HERMES\_WEBUI\_STATE\_DIR`을 해당 위치로 설정하세요(또는 디렉터리를 이동하세요). `HERMES\_HOME`이 설정되지 않았거나 기본 경로로 설치된 경우는 영향을 받지 않습니다. |
| `HERMES\_WEBUI\_DEFAULT\_WORKSPACE` | `~/workspace` | 기본 작업 공간 |
| `HERMES\_WEBUI\_DEFAULT\_MODEL` | \*(공급자 기본값)\* | 선택적 모델 오버라이드; 활성 Hermes 공급자 기본값을 사용하려면 비워 두세요 |
| `HERMES\_WEBUI\_PASSWORD` | \*(설정 안 함)\* | 비밀번호 인증을 활성화하려면 설정하세요 |
| `HERMES\_WEBUI\_CSP\_CONNECT\_EXTRA` | \*(설정 안 함)\* | 신뢰할 수 있는 리버스 프록시, 터널 또는 확장 사이드카 배포를 위해 강제 및 보고 전용 CSP `connect-src` 지시문에 추가할 선택적 공백으로 구분된 `http(s)://` 또는 `ws(s)://` 오리진 |
| `HERMES\_WEBUI\_SSE\_CHUNKED` | \*(설정 안 함)\* | `Transfer-Encoding: chunked`로 SSE를 보내려면 참 값(`1`/`true`/`yes`/`on`)으로 설정하세요. 전체 스트림을 버퍼링하는 버퍼링 리버스 프록시(예: `jupyter-server-proxy`) 뒤에서 필요하며, 직접 서비스되는 배포에서는 무해하지만 불필요합니다. |
| `HERMES\_WEBUI\_EXTENSION\_DIR` | \*(설정 안 함)\* | `/extensions/`에서 서빙되는 선택적 로컬 디렉터리; 확장 주입이 활성화되기 전에 존재하는 디렉터리를 가리켜야 합니다. |
| `HERMES\_WEBUI\_EXTENSION\_MANIFEST` | \*(설정 안 함)\* | 주입할 번들 스크립트/스타일을 나열하는 `HERMES\_WEBUI\_EXTENSION\_DIR` 내부의 선택적 상대 JSON 매니페스트; [WebUI Extensions](docs/EXTENSIONS.md) 참조 |
| `HERMES\_WEBUI\_EXTENSION\_SCRIPT\_URLS` | \*(설정 안 함)\* | 주입할 선택적 쉼표로 구분된 동일 출처 스크립트 URL; 매니페스트 스크립트 뒤에 추가됨; [WebUI Extensions](docs/EXTENSIONS.md) 참조 |
| `HERMES\_WEBUI\_EXTENSION\_STYLESHEET\_URLS` | \*(설정 안 함)\* | 주입할 선택적 쉼표로 구분된 동일 출처 스타일시트 URL; 매니페스트 스타일시트 뒤에 추가됨; [WebUI Extensions](docs/EXTENSIONS.md) 참조 |
| `HERMES\_HOME` | Windows: `%LOCALAPPDATA%\hermes`; POSIX: `~/.hermes` | Hermes 상태를 위한 기본 디렉터리 (모든 경로에 영향을 미침) |
| `HERMES\_CONFIG\_PATH` | `$HERMES\_HOME/config.yaml` | Hermes 설정 파일 경로 |
| `HERMES\_WEBUI\_SERVER\_CWD` | \*(설정 안 함)\* | 서버 프로세스의 작업 디렉터리입니다. 기본값은 에이전트 디렉터리입니다. 에이전트 디렉터리가 읽기 전용일 때 폴백 상대 쓰기가 쓰기 가능한 곳에 위치하도록 쓰기 가능한 작업 공간을 지정하세요. |
| `HERMES\_WEBUI\_AGENT\_CACHE\_MAX` | `25` | 인메모리 LRU에 활성 상태로 유지되는 최대 활성 에이전트 인스턴스 수입니다. 각 인스턴스는 전체 대화 기록을 고정하므로 상주 메모리에 미치는 주요 요인입니다. RAM을 제한하려면 세션이 길고 많은 설치에서 이 값을 낮추세요(더 많은 콜드 리로드 비용 발생). |
| `HERMES\_WEBUI\_SESSIONS\_MAX` | `100` | 인메모리 LRU에 유지되는 최대 컴팩트 `Session` 객체에 대한 레거시 운영자 오버라이드입니다. `config.yaml`의 `webui.sessions\_cache\_max` 키(우선순위가 높음)를 사용하는 것이 좋습니다. 이 환경 변수는 폴백으로 유지됩니다. 장기 실행 설치에서 지금까지 터치한 모든 세션을 누적하여 결국 충돌하는 것을 방지하기 위해 상주 메모리를 제한합니다(#4765/#2233/#4633). 퇴출(Eviction)은 항상 정리되고 지속되며 활성화되지 않은 세션만 삭제합니다. 퇴출된 세션은 다음 액세스 시 JSON 사이드카에서 지연 로드됩니다. |
확장 배포는 `GET /api/extensions/status`에서 정리되고 인증된 진단 정보를 검사할 수 있습니다. [WebUI Extensions](docs/EXTENSIONS.md#diagnostics)를 참조하세요.
---
### Nix flake 및 NixOS 모듈
Hermes WebUI에는

Nix flake 패키지와 NixOS 서비스 모듈이 제공되므로 선언적으로 실행할 수 있습니다.
다음 명령어로 최신 패키지를 설치하세요:
```bash
nix shell github:nesquena/hermes-webui#default
```
시스템 설정에서 다음 flake input을 사용하세요:
```nix
inputs.hermes-webui.url = "github:nesquena/hermes-webui";
```
그런 다음 `nixosModules`에 모듈을 추가하고 설정하세요:
```nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hermes-agent.url = "github:NousResearch/hermes-agent";
hermes-webui.url = "github:nesquena/hermes-webui";
};
outputs = { self, nixpkgs, hermes-agent, hermes-webui, ... }: {
nixosConfigurations. = nixpkgs.lib.nixosSystem {
modules = [
hermes-agent.nixosModules.default
hermes-webui.nixosModules.default
({ pkgs, ... }: {
services.hermes-agent.enable = true;
services.hermes-webui = {
enable = true;
host = "127.0.0.1";
port = 8787;
stateDir = "/var/lib/hermes-webui";
user = "hermes";
group = "hermes";
hermesHome = "/var/lib/hermes/.hermes";
agent.package = hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.default;
environmentFiles = [ "/run/secrets/hermes-webui.env" ];
};
})
];
};
};
}
```
모듈의 기본값은 `127.0.0.1`입니다. 직접 네트워크 액세스를 원할 때만 `host = "0.0.0.0"` 및 `openFirewall = true`로 설정하고, `environmentFiles`를 통한 `HERMES\_WEBUI\_PASSWORD`와 같은 인증을 함께 사용하세요.
배포된 Hermes Agent 패키지는 `passthru.hermesVenv`를 노출하므로, 모듈은 해당 인터프리터에서 `HERMES\_WEBUI\_PYTHON`을 파생합니다. 부트스트랩은 Agent 코드를 가져오지(import) 않고 해당 인터프리터를 통해 설치된 `run\_agent.py`를 찾아 상위 디렉토리를 `HERMES\_WEBUI\_AGENT\_DIR`로 내보냅니다. 패키지는 대신 직접 경로로 `passthru.hermesAgentDir`를 노출할 수도 있습니다. 커스텀 패키지 레이아웃을 명시적으로 오버라이드하려면 `agent.dir`과 `agent.python`을 사용하세요.
WebUI가 공유된 Hermes Agent 상태를 읽을 때, 해당 상태를 이미 읽을 수 있는 사용자로 서비스를 실행하세요. 동일한 위치에 있는 Hermes Agent 서비스의 경우, `user`와 `group`을 에이전트 서비스 계정으로 설정하세요. 모듈은 기본 `hermes-webui` 계정만 생성하며 기존 `hermesHome`의 소유권을 변경하지 않습니다.
이 모듈은 다음을 포함하여 기존 WebUI 환경 변수와 직접 매핑됩니다:
`HERMES\_WEBUI\_HOST`, `HERMES\_WEBUI\_PORT`, `HERMES\_WEBUI\_STATE\_DIR`, `HERMES\_HOME`, `HERMES\_WEBUI\_AGENT\_DIR`, `HERMES\_WEBUI\_PYTHON`.
API 키와 같은 보안 비밀을 위해 `environmentFiles`를 설정하세요. 모듈의 보호된 WebUI 런타임 키는 이곳에서 거부되므로, 호스트, 포트, 상태 및 에이전트 연결은 모듈 옵션에 유지하세요. 리버스 프록시 및 TLS 설정은 배포 세부 정보에 따라 다르므로 주변 배포 모듈에 유지하세요.
### 원격 액세스 (SSH 터널, Tailscale, 스마트폰)
서버는 기본적으로 `127.0.0.1`에 바인딩됩니다. 다른 기기에서 접근하려면 SSH 터널을 사용하거나 (`ssh -N -L 8787:127.0.0.1:8787 user@host`, `start.sh`가 SSH를 통해 출력해 줍니다), 서버와 스마트폰을 [Tailscale](https://tailscale.com) 네트워크에 연결하고 `HERMES\_WEBUI\_HOST=0.0.0.0` + `HERMES\_WEBUI\_PASSWORD`가 설정된 상태로 `http://:8787`에 접속하세요. 전체 안내서 (커뮤니티 ARM64-Android 현장 보고서 포함): [`docs/remote-access.md`](docs/remote-access.md).
### 수동 실행 (start.sh 없이)
서버를 직접 실행하려면:
```bash
cd /path/to/hermes-agent # 또는 sys.path가 Hermes 모듈을 찾을 수 있는 곳
HERMES\_WEBUI\_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py
```
참고: 에이전트 venv Python(또는 Hermes 에이전트 종속성이 설치된 모든 Python 환경)을 사용하세요. 시스템 Python에는 `openai`, `httpx` 및 기타 필수 패키지가 누락되어 있습니다.
상태 확인:
```bash
curl http://127.0.0.1:8787/health
```
---
## Docker
\*\*사전 빌드된 이미지\*\* (amd64 + arm64)는 모든 릴리스마다 GHCR에 게시됩니다.
3개의 compose 파일, 일반적인 오류 모드 및 바인드 마운트 마이그레이션을 다루는 포괄적인 설정 가이드는 [`docs/docker.md`](docs/docker.md)를 참조하세요. README는 5분 만에 시작하는 방법을 다룹니다.
### 5분 빠른 시작 (단일 컨테이너)
가장 간단한 설정: 단일

에이전트를 인프로세스로 실행하는 WebUI 컨테이너입니다.
```bash
git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# Edit .env if your host UID isn't 1000 (e.g. macOS where UIDs start at 501)
docker compose up -d
# Open http://localhost:8787
```
Hermes 홈 디렉터리의 소유자인 사용자로 Compose를 실행하세요. `sudo docker compose up -d`를 사용하면 `${HOME}`이 root 사용자의 홈으로 확장될 수 있으며, 이로 인해 Docker가 실제 `~/.hermes` 대신 잘못된 `.hermes` 디렉터리를 마운트하게 되어 WebUI가 `config.yaml (not found, using defaults)` 메시지와 함께 시작됩니다. 가능하면 사용자를 Docker 그룹에 추가하고 `docker compose up -d`를 실행하는 것을 권장합니다. 부득이하게 sudo를 사용해야 하는 경우 절대 경로를 먼저 설정하세요. 예를 들어 `HERMES\_HOME=/home/you/.hermes HERMES\_WORKSPACE=/home/you/workspace sudo -E docker compose up -d`와 같이 실행한 뒤 `docker compose config`로 확인하세요.
컨테이너는 마운트된 `~/.hermes` 볼륨에서 사용자의 UID/GID를 자동으로 감지하므로, 에이전트가 작성한 파일들을 호스트에서 그대로 읽을 수 있습니다.
비밀번호 보호를 활성화하려면 (`127.0.0.1` 외부에 포트를 노출하는 경우 필수):
```bash
echo "HERMES\_WEBUI\_PASSWORD=change-me-to-something-strong" >> .env
docker compose up -d --force-recreate
```
### 수동 `docker run` (compose 없음)
```bash
docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
-e WANTED\_UID=$(id -u) -e WANTED\_GID=$(id -g) \
-v ~/.hermes:/home/hermeswebui/.hermes \
-e HERMES\_WEBUI\_STATE\_DIR=/home/hermeswebui/.hermes/webui \
-v ~/workspace:/workspace \
-p 127.0.0.1:8787:8787 \
ghcr.io/nesquena/hermes-webui:latest
```
### 로컬 빌드
```bash
docker build -t hermes-webui .
docker run -d \
-e WANTED\_UID=$(id -u) -e WANTED\_GID=$(id -g) \
-v ~/.hermes:/home/hermeswebui/.hermes \
-e HERMES\_WEBUI\_STATE\_DIR=/home/hermeswebui/.hermes/webui \
-v ~/workspace:/workspace \
-p 127.0.0.1:8787:8787 \
hermes-webui
```
### 멀티 컨테이너 설정
에이전트와 WebUI를 별도의 컨테이너로 분리하고 싶거나(격리 목적, 혹은 다른 곳에서 이미 에이전트 게이트웨이를 실행 중인 경우):
```bash
# Agent + WebUI
docker compose -f docker-compose.two-container.yml up -d
# Agent + Dashboard + WebUI
docker compose -f docker-compose.three-container.yml up -d
```
두 compose 파일 모두 기본적으로 \*\*이름이 지정된 Docker 볼륨(named Docker volumes)\*\*을 사용하여 UID/GID 문제를 구조적으로 해결합니다. 기존 호스트 디렉터리를 공유하기 위해 바인드 마운트가 필요한 경우 전체 마이그레이션 방법은 [`docs/docker.md`](docs/docker.md)를 참조하세요.
> \*\*알려진 제한 사항 (#681)\*\*: 2개 컨테이너 설정에서는 WebUI에서 트리거된 도구가 에이전트 컨테이너가 아니라 \*\*WebUI 컨테이너\*\*에서 실행됩니다. WebUI의 파일 시스템에서 git/node 등이 필요한 경우 단일 컨테이너 설정을 사용하거나, WebUI Dockerfile을 확장하거나, 커뮤니티 [all-in-one 이미지](https://github.com/sunnysktsang/hermes-suite)를 사용하세요.
>
> \*\*소스 경계 노트 (#2453)\*\*: 멀티 컨테이너 설정은 기본적으로 `hermes-agent-src`를 읽기 전용으로 WebUI에 마운트합니다. 이는 WebUI 측의 소스 재작성을 방지하지만, 안정적인 Agent API 경계가 아닌 구현 결합 브리지일 뿐입니다. 현재 소스/API 분리 현황은 [`docs/rfcs/agent-source-boundary.md`](docs/rfcs/agent-source-boundary.md)를 참조하세요.
### 일반적인 오류 유형
| 증상 | 예상 원인 | 해결 방법 |
|---|---|---|
| 시작 시 `PermissionError` 발생 | 바인드 마운트의 UID 불일치 | `.env`에 `UID=$(id -u)` 설정 |
| `.env: permission denied` (#1389) | `fix\_credential\_permissions()`가 0600 권한 강제 적용 | `.env`에 `HERMES\_SKIP\_CHMOD=1` 설정 |
| 워크스페이스가 비어 보임 | `/workspace` 마운트의 UID 불일치 | `.env`에 `UID=$(id -u)` 설정 |
| 채팅에서 `git: command not found` 발생 | 2개 컨테이너 아키텍처 제한 (#681) | 단일 컨테이너 사용 또는 Dockerfile 확장 |
| WebUI가 에이전트 소스를 찾지 못함 | `hermes-agent-src` 볼륨 설정 오류 | compose 파일의 명명된 볼륨(named volumes)을 그대로 사용 |
| Podman 공유 `.hermes` 실패 | Podman 3.4의 `keep-id` 제한 | Podman 4 이상 또는 단일 컨테이너 사용 |
| WebUI에서 `localhost`의 호스트 API 연결 실패 | 컨테이너에서의 `localhost`는 호스트가 아닌

our host (#3012) | Docker Desktop에서는 `http://host.docker.internal:`을 사용하고, Podman에서는 `http://host.containers.internal:`을 사용하세요 |
| `sudo docker compose` 실행 후 WebUI에서 `~/.hermes`를 찾을 수 없는 문제 | `${HOME}`이 root 사용자의 홈 디렉터리로 확장됨 (#3006) | 일반 사용자 권한으로 Compose를 실행하거나, `sudo -E`와 함께 절대 경로 `HERMES\_HOME`/`HERMES\_WORKSPACE`를 전달하세요 |
이 각각에 대한 자세한 내용은 [`docs/docker.md`](docs/docker.md)를참고하세요.
> \*\*참고:\*\* 기본적으로 Docker Compose는 `127.0.0.1`(로컬호스트 전용)에 바인딩됩니다.
> 네트워크에 노출하려면 `docker-compose.yml`에서 포트를 `"8787:8787"`로 변경하고
> `HERMES\_WEBUI\_PASSWORD`를 설정하여 인증을 활성화하세요.
---
## 테스트 실행하기
테스트는 하드코딩된 경로 없이 저장소와 Hermes agent를 동적으로 탐지합니다.
로컬 실행 시 지원되지 않는 시스템 Python이 실수로 사용되지 않도록 저장소 테스트 러너를 사용하세요. Python 3.11, 3.12 또는 3.13으로 `.venv`를 생성/사용하며, 개발용 테스트 의존성이 누락된 경우 `requirements-dev.txt`에서 설치합니다.
```bash
cd hermes-webui
./scripts/test.sh
```
특정 테스트를 집중적으로 실행하려면 스크립트 뒤에 일반 pytest 인수를 전달하세요:
```bash
./scripts/test.sh tests/test\_regressions.py -v
```
또는 명시적으로 지원되는 기본 인터프리터로부터 저장소의 `.venv`를 시드(seed)할 수 있습니다:
```bash
HERMES\_WEBUI\_TEST\_PYTHON=/path/to/python3.12 ./scripts/test.sh tests/ -v
```
이 재정의 설정은 `.venv`를 생성하거나 재구축하는 데 사용되는 Python을 선택합니다. 의존성은 시스템/Homebrew 인터프리터가 아니라 여전히 저장소 로컬 가상 환경에 설치됩니다.
테스트는 별도의 상태 디렉터리를 가진 격리된 서버 환경에서 실행됩니다.
프로덕션 데이터와 실제 cron 작업은 절대 건드리지 않습니다. 현재 스냅샷 기준:
Python 3.11, 3.12, 3.13에서 CI로 실행되는 총 \*\*~1,150개의 테스트 파일\*\*에 걸쳐 \*\*~11,500개의 테스트가 수집\*\*되었습니다(각각 3개의 병렬 샤드).
---
## 아키텍처
빌드 단계, 프레임워크, 번들러 없음 — Python 표준 라이브러리 HTTP 서버와 바닐라 JS로 구성되어 있습니다. 백엔드는 `api/`에, 프론트엔드는 `static/`에 있습니다.
\*\*백엔드 (`api/`)\*\*
```
server.py HTTP 라우팅 셸 + 인증 미들웨어
api/
auth.py 선택적 비밀번호 인증, 서명된 쿠키, 패스키
config.py 탐지, 전역 변수, 모델 감지, 리로드 가능한 설정
helpers.py HTTP 헬퍼, 보안 헤더
models.py 세션 모델 + CRUD + CLI/state.db 브리지
onboarding.py 최초 실행 온보딩 마법사, OAuth 제공자 지원
profiles.py 프로필 상태 관리, hermes\_cli 래퍼
routes.py 모든 GET + POST 라우트 핸들러 (if/elif 디스패치, 데코레이터 없음)
state\_sync.py /insights 동기화 — message_count를 state.db로 동기화
streaming.py SSE 엔진, run\_agent, 취소, 압축
updates.py 자체 업데이트 확인 및 릴리스 노트
upload.py 멀티파트 파서, 파일 업로드 핸들러
workspace.py 파일 작업, 워크스페이스 헬퍼, git 감지
```
\*\*프론트엔드 (`static/`)\*\*
```
index.html HTML 템플릿
style.css 모바일 반응형, 테마 및 스킨을 포함한 모든 CSS
ui.js DOM 헬퍼, renderMd, 도구 카드, 컨텍스트 표시기
workspace.js 파일 미리보기, 파일 작업, git 배지, 중앙 api() fetch 래퍼
sessions.js 세션 CRUD, 접을 수 있는 그룹, 검색, 리로드 복구
messages.js send(), SSE 핸들러, 라이브 스트리밍, 세션 복구
panels.js Cron, 스킬, 메모리, 프로필, 설정 (제어 센터)
commands.js 슬래시 명령어 자동완성
boot.js 모바일 내비게이션, 음성 입력, 테마/스킨 부트, bfcache 핸들러
```
\*\*테스트 + 패키징\*\*
```
tests/ Pytest 스위트 (~11,500개 테스트; 격리된 서버/상태 픽스처)
pyproject.toml 표준 빌드 메타데이터 및 Ruff 린트 게이트; 체크아웃 실행 표면은 여전히 bootstrap.py / start.sh / ctl.sh 중심
Dockerfile python:3.12-slim 컨테이너 이미지
docker-compose.yml 이름이 지정된 볼륨과 선택적 인증이 포함된 Compose
.github/workflows/ CI: ruff + 샤딩된 pytest, 브라우저 스모크, Docker 스모크,
멀티 아키텍처 Docker 빌드 + 태그 시 GitHub Release
```
상태는 기본적으로 저장소 외부에 있는 `~/.hermes/webui/`에 저장됩니다
(세션, 워크스페이스, 설정, 프로젝트, last\_workspace). `HERMES\_WEBUI\_STATE\_DIR`를 사용하여 재정의할 수 있습니다.
전체 디자인 노트와 엔드포인트 카탈로그는 [`ARCHITECTURE.md`](ARCHITECTURE.md)에 있습니다.
---
#

# 호환성
WebUI 런타임 상태에 표시되는 버전은 \*\*WebUI 버전 전용\*\*입니다(현재 실행 중인 빌드/이미지/태그). 이는 완전한 호환성 맵이 아닙니다.
WebUI는 [#1925](https://github.com/nesquena/hermes-webui/issues/1925) 및 [#2491](https://github.com/nesquena/hermes-webui/issues/2491)의 안정적인 에이전트 경계 작업이 완료될 때까지 런타임 실행, 프로바이더/모델 접근, 상태/스키마 사용을 위해 여전히 Hermes Agent 내부 구조와 결합되어 있습니다. 실제로 WebUI는 Agent 모듈을 직접 임포트하고(`api/config.py`, `api/providers.py`, `api/streaming.py`) Agent 상태 레이아웃을 직접 읽기 때문에, 버전 불일치로 인해 임포트 오류나 동작 드리프트가 발생할 수 있습니다.
\*\*호환성 정책\*\*
- WebUI 릴리스 브랜치는 해당 WebUI 릴리스 시점에 제공되는 일치하는 Hermes Agent 릴리스를 기준으로 테스트됩니다.
- \*\*둘 다 함께 업그레이드하세요\*\*: 특히 프로덕션 트래픽을 활성화하기 전에 WebUI와 hermes-agent를 함께 업그레이드하거나 고정(pin)하세요(동일한 릴리스 트레인/버전/날짜).
- [#1925](https://github.com/nesquena/hermes-webui/issues/1925) / [#2491](https://github.com/nesquena/hermes-webui/issues/2491)의 안정적인 API 경계 작업이 완료되기 전까지는 버전을 고정하여 구버전과 신버전을 조합하는 방식은 \*\*테스트되지 않았으며 지원되지 않습니다\*\*.
- 업그레이드 불일치가 의심되는 이슈 신고 시 전체 `hermes-agent` + `hermes-webui` 버전을 기록해 주세요.
\*\*Docker 사용자\*\*: 한쪽에는 `latest`를 사용하고 다른 쪽에는 고정된 태그를 사용하는 대신, 양쪽 이미지 태그(또는 이에 상응하는 고정된 소스 리비전)를 모두 고정하세요. 멀티 컨테이너 설정을 업그레이드할 때는 [`docs/docker.md`](docs/docker.md)의 에이전트 이미지 업그레이드 절차를 따르세요(재생성하기 전에 `hermes-agent-src` 볼륨을 삭제해야 함). 현재 소스 경계 상태는 [`docs/rfcs/agent-source-boundary.md`](docs/rfcs/agent-source-boundary.md)에서 추적됩니다.
---
## 문서
\*\*여기서 시작하세요\*\*
- [`docs/why-hermes.md`](docs/why-hermes.md) — Hermes를 선택하는 이유, 멘탈 모델, 그리고 Claude Code / Codex / OpenCode / Cursor와의 상세한 비교
- [`docs/onboarding.md`](docs/onboarding.md) — 첫 실행 마법사, 프로바이더 설정, 로컬 모델 서버 Base URL, 안전한 재실행 방법
- [`docs/troubleshooting.md`](docs/troubleshooting.md) — 일반적인 오류에 대한 진단 흐름(예: "AIAgent not available")
\*\*사용 및 사용자 지정\*\*
- [`THEMES.md`](THEMES.md) — 테마 및 스킨 시스템, 커스텀 테마 가이드
- [`docs/workspace-git.md`](docs/workspace-git.md) — 워크스페이스 Git 제어 기능
- [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) — 관리자가 제어하는 WebUI 확장 주입
\*\*배포 및 운영\*\*
- [`docs/remote-access.md`](docs/remote-access.md) — SSH 터널, Tailscale 및 모바일 접근(커뮤니티 ARM64-Android 필드 리포트 포함)
- [`docs/advanced-chat-setup.md`](docs/advanced-chat-setup.md) — 자체 호스팅 배포를 위한 선택적 동적 리콜 프리필 및 Gateway 기반 브라우저 채팅
- [`docs/docker.md`](docs/docker.md) — Docker compose 설정, 일반적인 오류 및 바인드 마운트 마이그레이션
- [`docs/supervisor.md`](docs/supervisor.md) — launchd, systemd, supervisord, runit 및 s6 프로세스 슈퍼바이저 설정
- [`docs/wsl-autostart.md`](docs/wsl-autostart.md) — Windows 로그인 시 WSL2 자동 시작
- [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) — 어시스턴트 주도 설치/재설치 지원을 위한 안전 규칙 및 통과/실패 검사 항목
\*\*기여 및 디자인\*\*
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — 기여 스타일, PR 요구 사항 및 로컬 검증
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — 시스템 설계, 모든 API 엔드포인트, 구현 참고 사항
- [`TESTING.md`](TESTING.md) — 수동 브라우저 테스트 계획 및 자동화된 커버리지 참조
- [`DESIGN.md`](DESIGN.md) — 디자인 토큰 및 calm-console 방향성
- [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md) — 디자인 문서 및 시각적 인벤토리에서 가져온 UI/UX 원칙
- [`docs/CONTRACTS.md`](docs/CONTRACTS.md) — 기여자 및 에이전트를 위한 프로젝트 계약/RFC/디자인 색인
- [`docs/rfcs/README.md`](docs/rfcs/README.md) — 대규모 아키텍처 변경을 위한 RFC 색인

아키텍처 및 내구성 제안
\*\*릴리스 내역 및 계획\*\*
- [`CHANGELOG.md`](CHANGELOG.md) — 버전별 릴리스 노트
- [`ROADMAP.md`](ROADMAP.md) — 기능 로드맵 및 스프린트 내역
- [`SPRINTS.md`](SPRINTS.md) — CLI + Claude 패리티 목표를 포함한 향후 스프린트 계획
- [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — 전체 커뮤니티 기여자 명단
---
## 기여자 (Contributors)
Hermes WebUI는 오픈소스 커뮤니티의 도움으로 제작되었습니다. 직접 병합되었든, 일괄 릴리스에 흡수되었든, 혹은 더 큰 제안에서 구제되었든 상관없이 모든 PR은 프로젝트를 구체화하며, 시간을 내어 기여해주신 모든 분께 감사드립니다.
\*\*326명이 넘는 기여자\*\*가 릴리스 태그에 포함된 코드를 작성했습니다. 1~2개의 PR을 기여한 모든 분들과 디자인 및 아키텍처 작업에 대한 특별 감사의 명단을 포함하여, 지속적으로 업데이트되는 전체 기여자 명단은 [`CONTRIBUTORS.md`](CONTRIBUTORS.md)에서 확인할 수 있습니다. 가장 활발하게 기여한 분들의 요약은 다음과 같습니다:
### 상위 기여자 (PR 수 기준, 흡수/일괄 릴리스된 작업 포함)
| # | 기여자 | PR 수 | 첫 번째 → 최신 릴리스 |
|---|---|---:|---|
| 1 | [@rodboev](https://github.com/rodboev) | 336 | `v0.51.223` → `v0.51.893` |
| 2 | [@franksong2702](https://github.com/franksong2702) | 301 | `v0.49.3` → `v0.51.893` |
| 3 | [@Michaelyklam](https://github.com/Michaelyklam) | 157 | `v0.50.240` → `v0.51.198` |
| 4 | [@ai-ag2026](https://github.com/ai-ag2026) | 121 | `v0.50.279` → `v0.51.835` |
| 5 | [@bergeouss](https://github.com/bergeouss) | 80 | `v0.48.0` → `v0.51.703` |
| 6 | [@AJV20](https://github.com/AJV20) | 57 | `v0.51.93` → `v0.51.346` |
| 7 | [@dso2ng](https://github.com/dso2ng) | 43 | `v0.50.227` → `v0.51.578` |
| 8 | [@starship-s](https://github.com/starship-s) | 28 | `v0.50.123` → `v0.51.763` |
| 9 | [@Sanjays2402](https://github.com/Sanjays2402) | 27 | `v0.50.292` → `v0.51.484` |
| 10 | [@allenliang2022](https://github.com/allenliang2022) | 24 | `v0.51.185` → `v0.51.869` |

총 326명의 기여자 전체 순위 목록(3개 이상의 PR 테이블, 1~2개 PR 명단, 그리고 디자인 및 아키텍처 기여에 대한 특별 감사 노트)은 [`CONTRIBUTORS.md`](CONTRIBUTORS.md)를 참조하세요.

### 주요 기여
\*\*[@franksong2702](https://github.com/franksong2702)\*\* — 가장 활발한 외부 기여자 (180개 PR, `v0.49.3` → `v0.51.384`)
외부 기여자 중 가장 오랜 기간 동안 다음과 같은 기여를 했습니다: 세션 제목 가드(#301), 브레드크럼 워크스페이스 탐색(#302), 임베디드 워크스페이스 터미널(#1099), 워크트리 기반 세션 생성(#2053), 온보딩 문서(#2052), 컴포저 하단 컨테이너 쿼리, 스트리밍 세션 사이드바 예외 처리(#1327), 세션 사이드카 복구, cron 출력 보존(#1295), 프로필 기본 워크스페이스 유지, 수동 `/compress` 비동기 시작/상태 엔드포인트(#2128), 수명 주기 통합 #2057을 위한 워크트리 상태 서피스(#2109) + 가드된 제거(#2156), 세션 렌더링 후 중복 제거(#2166), 네이티브 WebUI 빠른 경로(#2170), 테일 윈도우 응답 트림(#2171), 오래된 스트림 가드 확장(#2158), CSP 리포트 수집기(#2160), 그리고 모바일/반응형, 세션 사이드바, 워크스페이스 상태 기계 전반에 걸친 수많은 다듬기 작업.

\*\*[@Michaelyklam](https://github.com/Michaelyklam)\*\* — 최근 릴리스에서 가장 활발한 기여자 (118개 PR, `v0.50.240` → `v0.51.198`)
프로덕션 Docker 강화(#1921, sudo 권한 스테이징 사용자 제거), 프로필 범위 스킬 엔드포인트(#1903), 프로필 범위 HERMES\_HOME 하의 게이트웨이 PID 해상도(#1901), 프로필 인식 AIAgent 캐시(#1898/#1904), 백슬래시 LaTeX 구분 기호(#1848), Codex 할당량 초과 오류 표시(#1770), 셸 라우트 HTML 503(#1836), 오래된 칸반 클라이언트 복구(#1828), 컨텍스트 자동 압축 토스트 수명(#1988), `/goal` 명령어(#1866), 칸반 상세 보기 스크롤(#1916), CLI 세션 도구 메타데이터 보존(#1778), 번체 중국어 칸반 로케일 백필(#1979), v0.51.51 모바일 Insights 버킷팅/레이아웃(#2120/#2121), Hermes 실행 어댑터 RFC(#2105 대안 #1925), 여기서부터 포크 절대 인덱스(#2198 대안 #2184)

), opencode-go 커스텀 제공자 중복 라우팅(#2204, #1894 관련).
\*\*[@rodboev](https://github.com/rodboev)\*\* — Windows / 크로스 플랫폼 정확성 + 테스트 안정성 (83개 PR, `v0.51.223` → `v0.51.384`)
Linux 외의 환경에서 프로젝트가 원활히 작동하도록 하는 데 강한 초점을 맞춘 광범위하고 지속적인 개선 작업: `ctl.sh` Windows 프로세스 트리 종료 수정(#3670), 로컬 Windows 전체 스위트 시그널/고아 프로세스 작업, 슬래시 명령어 자동 완성 다듬기, 그리고 수십 개의 릴리스 배치에 걸쳐 적용된 프론트엔드 및 인프라 수정 사항들입니다.
\*\*[@bergeouss](https://github.com/bergeouss)\*\* — 제공자 관리 UI + Docker 강화 (70개 PR, `v0.48.0` → `v0.51.385`)
설정에서 커스텀 제공자를 추가/편집하기 위한 제공자 관리 UI, OAuth 제공자 상태 감지(#1552), 투 컨테이너 Docker 설정, 프로필 격리 강화(프로필별 `.env` 시크릿), 사용자가 Settings → Providers를 이용할 때 볼 수 있는 대부분의 기능, Finder에서 보기 컨텍스트 메뉴(#1551), 게이트웨이 상태 카드(#1552), 활성 프로젝트 필터에 세션 자동 할당(#1550), 업데이트 배너의 "What's new?" 링크(#1549), OpenRouter 무료 티어 라이브 패치(#1548), 자격 증명 풀 401 자가 치유(#1553), 모델 선택기의 인라인 제공자 칩 + 그룹 모델 수(#1644).
\*\*[@ai-ag2026](https://github.com/ai-ag2026)\*\* — 세션 복구 + 감사 인프라 (75개 PR, `v0.50.279` → `v0.51.367`)
내구성 향상에 초점을 맞춘 자율 AI 기여자(Hermes Agent 구동): `state.db` 기반 사이드카 조화(#2041), 시작 시 고아 `.json.bak` 복구(#2035), 읽기 전용 세션 복구 감사 엔드포인트(#2036, #2040), `/health`의 활성 실행 생명주기(#2039), `docs/rfcs/turn-journal.md`의 크래시 안전 턴 저널 RFC(#2042), 추가 전용 턴 저널 헬퍼(#2059), 생명주기 이벤트 레이어(#2062), `Content-Security-Policy-Report-Only` 헤더(#2084), 크론별 토글(#2100), 포크 세션 압축 계보 격리(#2014).
\*\*[@dso2ng](https://github.com/dso2ng)\*\* — 세션 계보 + 진단 (30개 PR, `v0.50.227` → `v0.51.327`)
경계가 지정된 세션 그래프 진단을 위한 `/api/session/lineage-report/` 엔드포인트(#2012), 오래된 Mermaid 렌더링 오류 정리(#1337), `session\_source="fork"` 연속 체인 격리(#2063), 사이드바 배지 확장 시 지연 계보 보고서 패치(#2130), 그리고 세션 로딩과 관련된 수많은 프론트엔드 안정성 수정 사항들입니다.
\*\*[@jasonjcwu](https://github.com/jasonjcwu)\*\* — 컴포저 + 대화 내용 다듬기 (16개 PR, `v0.50.227` → `v0.51.132`)
활성 레일 클릭을 통한 사이드바 접기(#2054, #1884 및 #1924 병합), 컴포저 칩 라이트박스(#1758), 도구가 많은 첫 번째 턴의 제목 수정, 세션 전환 중 조용한 압축 상태 표시(#2185), 동시 전송 손실 수정(#2186), 대화 내용 내 조작 메시지 배지(#2187), 그리고 일련의 프론트엔드 다듬기 수정 사항들입니다.
\*\*[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)\*\* — 실라이브 스트리밍 + UX 다듬기 (12개 PR, `v0.50.18` → `v0.51.66`)
작업 공간 폴백 해결의 초기 스프린트, 실시간 추론 카드(#366, #367, #394–#397), 최근의 집중 개선: 제공자 할당량 카드의 수동 "Refresh usage" 버튼(#2150), 취소된 턴 상태 분류(#2151), Firefox 사이드바 스크롤 안정화(#2200), 조기 임시 세션 제목(#2202), 대상 인식 "What's new?" 업데이트 배너 링크(#2207), 설정의 MCP 도구 오버플로우 수정(#2210).
\*\*[@aronprins](https://github.com/aronprins)\*\* — `v0.50.0` UI 대개편 (PR #242 및 9개의 후속 PR)
프로젝트에 대한 가장 큰 단일 기여: 모델/프로필/작업 공간 컨트롤을 컴포저 하단으로 이동하고, 톱니바퀴 아이콘 설정 패널을 Hermes Control Center(탭 모달)로 교체하고, 활동 표시줄을 인라인 컴포저 상태로 대체하고, `⋯` 액션 드롭다운으로 세션 목록을 재설계하고, 작업 공간 패널 상태 기계를 추가한 완전한 UI 재설계입니다. 또한 채팅 대화 내용 재설계(#587), 사이드바 정리(#584), 3열 레이아웃 리팩터링(#899), 라이트/다크 테마 + 액센트 스킨(#627), 공유 `confirm()`/`prompt()` 대화상자 구현 포함

replacement (PR #251 extracted from #242).
\*\*[@iRonin](https://github.com/iRonin)\*\* — 보안 강화 스프린트 (PR #196–#204)
여섯 개의 연속적이고 집중적인 보안 PR: 세션 메모리 누수 수정(만료된 토큰 정리), CSP + Permissions-Policy 헤더, 30초 느린 클라이언트(slow-client) 연결 타임아웃, 환경 변수를 통한 선택적 HTTPS/TLS 지원, 자체 업데이트를 위한 업스트림 브랜치 추적 수정, 그리고 file-browser API에서의 CLI 세션 지원. 셀프 호스팅 도구를 신뢰할 수 있게 만들어 주는 집중적이고 완성도 높은 보안 작업입니다.
\*\*[@lucasrc](https://github.com/lucasrc)\*\* — 인증 강화 3부작 (PR #2191, #2192, #2193)
v0.51.57에 반영된 상호 연계된 세 개의 보안 PR: PBKDF2 키 분리가 적용된 스레드 세이프(thread-safe) 로그인 레이트 리미터(rate limiter), 설정 저장 시 패스워드 해시 캐시 무효화, 그리고 하위 호환 마이그레이션 브리지가 포함된 완전한 64바이트 HMAC-SHA256 세션 서명. 독립된 세 조각으로 리뷰할 수 있도록 깔끔하게 분해된 보안 작업입니다.
\*\*[@LumenYoung](https://github.com/LumenYoung)\*\* — 스트리밍 핫 패스(hot-path) 정확성 (8개의 PR, `v0.51.47` → `v0.51.99`)
오리지널 stale-stream 쓰기백 가드(#2136 — 다음 두 릴리스가 확장한 버그 클래스), 게이트웨이 상태 alive-null 분류(#2075), 압축 배너 앵커 정렬(#2182), 그리고 압축 완료 시 컨텍스트 진행 상황 링 자동 새로 고침(#2188). 각 PR은 코드베이스에서 가장 취약한 서브시스템 중 하나를 대상으로 작고 정교한 수정을 수행했습니다.
\*\*[@dobby-d-elf](https://github.com/dobby-d-elf)\*\* — 프론트엔드 안정성 + 모션 폴리시 (15개의 PR, `v0.51.38` → `v0.51.161`)
삭제된 디렉터리에 대한 워크스페이스 폴백(#2138), 아이폰 PWA 하단 스크롤 수정(#2143), 새로운 "Activity: X tools" 컴포저 푸터 쉬머 애니메이션(#2203), 그리고 후속 애니메이션 조정(#2212).
\*\*[@JKJameson](https://github.com/JKJameson)\*\* — 컴포저 + 세션 폴리시 (10개의 PR)
세션별 영구 컴포저 초안(#1956), 그리고 컴포저와 세션 사이드바 전반에 걸친 장기적인 완성도 개선 작업.
\*\*[@gabogabucho](https://github.com/gabogabucho)\*\* — 스페인어 로케일 + 온보딩 마법사
모든 UI 문자열을 지원하는 완전한 스페인어(`es`) 로케일, 그리고 첫 실행 시 신규 사용자의 프로바이더 설정을 안내하는 원샷 부트스트랩 온보딩 마법사.
\*\*[@deboste](https://github.com/deboste)\*\* — 리버스 프록시 인증 + 모바일 반응형 레이아웃 (PR #3, #4, #5)
초기 커뮤니티 PR 중 세 가지: 리버스 프록시 설정에서 URL origin을 사용하도록 EventSource/fetch 수정, 설정에서 모델 프로바이더 라우팅 수정, dvh 뷰포트 수정을 포함한 모바일 반응형 레이아웃 추가. 초기 기반 다지기 작업.
\*\*[@indigokarasu](https://github.com/indigokarasu)\*\* — 시각적 리디자인 제안 (PR #213)
전체 UI에 대한 CSS 전용 리디자인 — 적절한 디자인 토큰, 이모지 탭 스트립을 대체하는 아이콘 레일 사이브바, 일관된 폼 카드, 브레드크럼 네비게이션, 그리고 커스텀 프로퍼티로 구현된 7가지 내장 테마. PR이 그대로 병합되지는 않았지만 v0.50.0에 탑재된 디자인 언어와 테마 아키텍처의 기반이 되었습니다.
\*\*[@zenc-cp](https://github.com/zenc-cp)\*\* — ReAct 루프를 위한 환각(hallucination) 방지 가드 (PR #133)
스트리밍 파이프라인에서 여전히 사용 중인 3계층 접근 방식(임시 환각 방지 프롬프트, 라이브 토큰 필터링, 세션 히스토리 정리).
\*\*[@Hinotoi-agent](https://github.com/Hinotoi-agent)\*\* — 프로필 + 세션 보안 (PR #351, #2048)
프로필 간 API 키 유출을 방지하는 프로필 `.env` 시크릿 격리 수정(PR #351), 그리고 `/`를 대상으로 하는 조작된 JSON 파일 읽기를 차단하는 세션 임포트 워크스페이스 검증(PR #2048).
\*\*[@Sanjays2402](https://github.com/Sanjays2402)\*\* — 무한 스크롤 + 시작점 점프(Start-jump) 레이스 컨디션 수정 (PR #1949)
v0.51.30에서 발생한 무한 스크롤 프리페치와 Start-jump의 `\_ensureAllMessagesLoaded` 간의 레이스 컨디션을 해결한 제너레이션 토큰 + 뮤텍스 쌍. (#1942 및 #1962에서 제안된) 단순한 동일 플래그 확인 방식은 await 이후의 레이스 컨디션에 대해 아무런 동작을 하지 못했으며, Sanjays2402의 수정안이 올바른 형태였습니다.
\*\*[@fxd-jason](https://github.com/fxd-jason)\*\* — 실시간 승인 + 명확화

via SSE (PRs #1350, #1355)
승인(approval)과 명확화(clarify) 모두에 대해 1.5초 HTTP 폴링을 SSE 롱 커넥션(long-connection)으로 교체하여, 지연 시간을 최대 1.5초에서 거의 즉각적인 수준으로 단축했습니다. (원자적 구독 + 스냅샷, 락 내부 알림, 큐 헤드 페이로드, 트레일링 이벤트 재발행 등) 정확성에 대한 세부 사항들을 모두 올바르게 구현했습니다.
\*\*[@happy5318](https://github.com/happy5318)\*\* — 커스텀 프로바이더 모델 중복 제거 (PR #1947)
선택기(picker)에서 이름이 다른 서로 다른 커스텀 프로바이더의 동일한 모델이 조용히 중복 제거되던 문제를 수정했으며, 원본 테스트에서 Opus가 포착한 경쟁 상태(race condition)를 보완했습니다.
\*\*[@NocGeek](https://github.com/NocGeek)\*\* — 스트리밍 스크롤 + 수동 cron 출력 유지 (7개의 PR)
도구/큐 카드 삽입 시 스트리밍 스크롤 뷰포트 안정성 개선(#1360), 수동 cron 실행 출력 및 메타데이터 지속성 구현(#1372, 보류되었던 #1352에서 분리).
\*\*[@DavidSchuchert](https://github.com/DavidSchuchert)\*\* — 독일어 번역 (PR #190)
모든 UI 문자열, 설정 라벨, 명령어, 시스템 메시지를 포함하는 완전한 독일어 로케일(`de`)을 추가하고, i18n 시스템을 스트레스 테스트하여 아직 번역되지 않았던 여러 요소를 발견하고 동일 PR 내에서 수정했습니다.
\*\*[@Bobby9228](https://github.com/Bobby9228)\*\* — 모바일 Profiles 버튼 (PR #265)
모바일 내비게이션 플로우에 Profiles 항목을 추가하여 휴대전화에서도 프로필 전환이 가능하도록 만들었습니다.
\*\*[@kevin-ho](https://github.com/kevin-ho)\*\* — OLED 테마 (PR #168)
7번째 내장 테마: 화면 번인 위험을 줄이도록 조정된 웜 액센트가 적용된 순수 블랙 배경.
\*\*[@andrewy-wizard](https://github.com/andrewy-wizard)\*\* — 중국어 현지화 (PR #177)
간체 중국어(`zh`) 초기 로케일 추가. 영어 외의 언어로는 최초의 로케일 중 하나입니다.
\*\*[@DelightRun](https://github.com/DelightRun)\*\* — WebUI 세션을 위한 `session\_search` 수정 (PR #356)
모든 WebUI 세션에서 해당 도구를 조용히 중단시키고 있던 스트리밍 경로의 누락된 `SessionDB` 주입 문제를 추적하여 해결했습니다.
\*\*[@lawrencel1ng](https://github.com/lawrencel1ng)\*\* — Bandit 보안 수정 (PR #354)
체계적인 bandit 스캔 수정: `urlopen` 전 URL 스킴 검증, MD5 `usedforsecurity=False` 설정, 그리고 적절한 로깅으로 교체된 40개 이상의 단순 `except: pass` 블록.
\*\*[@shaoxianbilly](https://github.com/shaoxianbilly)\*\* — 유니코드 파일 이름 다운로드 (PR #378)
ASCII가 아닌 파일 이름도 다운로드 시 충돌이 발생하지 않도록 RFC 5987 `filename\*=UTF-8''...` 인코딩이 적용된 올바른 `Content-Disposition` 구현.
\*\*[@lx3133584](https://github.com/lx3133584)\*\* — 리버스 프록시를 위한 CSRF 수정 (PR #360)
Nginx Proxy Manager 등 80/443이 아닌 포트 뒤에서 호스팅하는 모든 사용자에게 영향을 주던 실제 운영 환경의 차단 이슈를 해결했습니다.
\*\*[@betamod](https://github.com/betamod)\*\* — 보안 감사 (PR #171)
v0.39.0에 포함된 포괄적인 CSRF / SSRF / XSS / 환경 변수 경쟁 상태(env-race-condition) 감사.
\*\*[@TaraTheStar](https://github.com/TaraTheStar)\*\* — 봇 이름 + 사고(thinking) 블록 + 로그인 리팩토링 (PRs #132, #176, #181)
설정 가능한 어시스턴트 표시 이름, 사고/추론 블록 표시, 로그인 페이지 리팩토링.
---
## Repo
```
git@github.com:nesquena/hermes-webui.git
```

hermes-webui

hermes-webui 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

hermes-webui

hermes-webui 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README