nesquena/hermes-webui

Hermes Agent는 사용자의 서버에서 작동하는 정교한 자율 에이전트(autonomous agent)로, 터미널이나 메시징 앱을 통해 접근할 수 있으며, 학습한 내용을 기억하고 실행 시간이 길어질수록 역량이 향상됩니다.

Hermes WebUI는 Hermes Agent를 위한 가볍고 다크 테마의 웹 애플리케이션 인터페이스입니다. CLI(Command Line Interface) 경험과 완벽하게 동등합니다. 터미널에서 할 수 있는 모든 것을 이 UI에서도 할 수 있습니다. 빌드 단계, 프레임워크, 번들러가 필요 없습니다. 파이썬(Python)과 바닐라 JS(vanilla JS)만 사용했습니다.

레이아웃은 세 개의 패널로 구성됩니다. 왼쪽 사이드바는 세션 및 탐색을 담당하고, 중앙은 채팅 영역이며, 오른쪽은 워크스페이스 파일 브라우징 공간입니다. 모델, 프로필, 그리고 워크스페이스 제어 기능은 **컴포저 푸터(composer footer)**에 위치하며, 작성하는 동안 항상 보입니다. 원형 컨텍스트 링(context ring)이 토큰 사용량을 한눈에 보여줍니다. 모든 설정과 세션 도구는 Hermes Control Center (사이드바 하단의 런처)에서 찾을 수 있습니다.

전체 프로필 지원 기능이 있는 라이트 모드
|
설정을 사용자 정의하고 비밀번호를 구성하는 화면
|
인라인 미리보기가 가능한 워크스페이스 파일 브라우저
|
세션 프로젝트, 태그 및 도구 호출 카드
|
이것은 사용자가 Hermes 설정에서 SSH 터널을 통해 안전하게 접근할 수 있는 편리한 웹 UI를 통해 Hermes CLI와 거의 1:1의 동등성을 제공합니다. 시작하는 단일 명령과 컴퓨터에 접속하기 위한 SSH 터널링 단일 명령만 필요합니다. 웹 UI의 모든 부분은 추가적인 설정 없이 기존 Hermes 에이전트와 기존 모델을 사용합니다.

• Why Hermes — 정의 및 비교 방법
• 빠른 시작 — 클론 +
  bootstrap.py

/start.sh`

/ctl.sh`

• 기능 — 채팅, 세션, 워크스페이스, 음성(voice), 프로필, 보안, 테마, 패널, 모바일
• 설정 및 접근 — 자동 감지(auto-discovery), 오버라이드(overrides), 원격/Tailscale/폰, 수동 실행
• Docker — 단일 및 다중 컨테이너 배포
• 테스트 실행
• 아키텍처 — 백엔드/프론트엔드 레이아웃, 상태 디렉토리(state dir)
• 문서 — 전체 문서 인덱스
• 기여자(Contributors)

대부분의 AI 도구들은 세션마다 초기화됩니다. 이들은 당신이 누구인지, 무엇을 작업했는지, 혹은 당신의 프로젝트가 어떤 컨벤션 (conventions)을 따르는지 알지 못합니다. 당신은 매번 자신을 다시 설명해야 합니다.

Hermes는 세션 전반에 걸쳐 컨텍스트 (context)를 유지하며, 당신이 오프라인인 동안에도 예약된 작업 (scheduled jobs)을 실행하고, 실행 시간이 길어질수록 당신의 환경에 대해 더 똑똑해집니다. 기존의 Hermes 에이전트 (agent) 설정과 기존 모델들을 그대로 사용하며, 시작하기 위해 추가적인 설정이 필요하지 않습니다.

다른 에이전트 도구 (agentic tools)들과 차별화되는 점:

지속성 메모리 (Persistent memory)— 사용자 프로필, 에이전트 노트, 그리고 재사용 가능한 절차를 저장하는 기술 시스템 (skills system); Hermes는 당신의 환경을 학습하며 매번 다시 학습할 필요가 없습니다.
셀프 호스팅 스케줄링 (Self-hosted scheduling)— 당신이 오프라인인 동안 실행되어 Telegram, Discord, Slack, Signal, 이메일 등으로 결과를 전달하는 크론 잡 (cron jobs).
10개 이상의 메시징 플랫폼— 터미널에서 사용 가능한 것과 동일한 에이전트를 휴대폰에서도 사용할 수 있습니다.
자기 개선 기술 (Self-improving skills)— Hermes는 경험으로부터 자신의 기술을 자동으로 작성하고 저장합니다; 찾아볼 마켓플레이스도, 설치할 플러그인도 필요 없습니다.
공급자 불가지론 (Provider-agnostic)— OpenAI, Anthropic, Google, DeepSeek, OpenRouter 등을 지원합니다.
다른 에이전트 오케스트레이션 (Orchestrates other agents)— 무거운 코딩 작업을 위해 Claude Code나 Codex를 생성하고 그 결과를 자신의 메모리로 다시 가져올 수 있습니다.
셀프 호스팅 (Self-hosted)— 당신의 대화, 당신의 메모리, 당신의 하드웨어.

기존 도구들과의 비교 (vs. the field) (업계 지형은 활발히 변화 중입니다 — 전체 분석은 docs/why-hermes.md를 참조하세요):

비교 항목	OpenClaw	Claude Code	Codex CLI	OpenCode	Hermes
지속성 메모리 (자동)	Yes	Partial†	Partial	Partial	Yes
...
† Claude Code는 CLAUDE.md / MEMORY.md 프로젝트 컨텍스트와 순환형 자동 메모리 (rolling auto-memory)를 가지고 있지만, 세션 간의 완전한 자동 회상 (cross-session recall) 기능은 없습니다.

‡ Claude Code는 클라우드 관리형 스케줄링 (Anthropic 인프라)과 세션 범위의 /loop를 제공합니다.

; 셀프 호스팅 크론 (cron) 없음

가장 가까운 경쟁자는 OpenClaw입니다 — 두 프로젝트 모두 메모리(memory), 크론(cron), 메시징(messaging) 기능을 갖춘 상시 가동형(always-on), 셀프 호스팅(self-hosted), 오픈 소스 에이전트(agent)입니다. 주요 차이점은 다음과 같습니다: Hermes는 핵심 동작으로서 자신의 기술(skills)을 자동으로 작성하고 저장하지만 (OpenClaw의 기술 시스템은 커뮤니티 마켓플레이스 중심입니다); Hermes는 업데이트 시 더 안정적입니다 (OpenClaw는 문서화된 릴리스 회귀(regressions)가 있으며, ClawHub는 악성 기술과 관련된 보안 사고가 있었습니다); 그리고 Hermes는 Python 생태계에서 네이티브로 실행됩니다. 전체적인 비교 내용은 docs/why-hermes.md를 참조하세요.

저장소 부트스트랩(bootstrap)을 실행합니다:

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

또는 셸 런처(shell launcher)를 계속 사용하려면:

./start.sh

셀프 호스팅 VM 또는 홈랩(homelab) 설치의 경우, ctl.sh는 fuser나 pkill을 요구하지 않고 일반적인 데몬(daemon) 생명주기 명령을 래핑(wrap)합니다:

./ctl.sh start # 백그라운드 데몬, PID는 ~/.hermes/webui.pid에 저장
./ctl.sh status # PID, 가동 시간(uptime), 바인딩된 호스트/포트, 로그 경로, /health
./ctl.sh logs --lines 100 # tail ~/.hermes/webui.log
...

ctl.sh start는 데몬 래퍼(daemon wrapper) 뒤에서 포그라운드/브라우저 미사용(no-browser) 모드로 부트스트랩을 실행하고, 로그를 ~/.hermes/webui.log에 기록하며, .env 파일 및 HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start와 같은 인라인 오버라이드(inline overrides)를 준수합니다.

두 가지 선택적인 셀프 호스팅 배포 기능 — 브라우저 턴(browser turns)에 동적 **세션 회상 프리필(session-recall prefill)**을 연결하는 것(Joplin/Obsidian/Notion/llm-wiki 라우터)과 실행 중인 Hermes Gateway를 통해 브라우저 채팅을 라우팅하는 것 — 은 docs/advanced-chat-setup.md에 문서화되어 있습니다. 대부분의 사용자는 두 기능 모두 필요하지 않습니다.

부트스트랩은 다음을 수행합니다:

• Hermes Agent를 감지하고, 없는 경우 공식 설치 프로그램(curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash)을 시도합니다.
• WebUI 의존성(dependencies)을 포함하는 Python 환경을 찾거나 생성합니다.
• 웹 서버를 시작하고 /health를 기다립니다.
• --no-browser를 전달하지 않는 한 브라우저를 엽니다.

. - WebUI 내부의 첫 실행 온보딩 마법사(onboarding wizard)로 안내합니다.

이 부트스트랩(bootstrap)은 아직 네이티브 Windows를 지원하지 않습니다. Linux, macOS 또는 WSL2를 사용하세요. Windows / WSL 로그인 시 자동 시작에 대해서는 다음을 참조하세요:

docs/wsl-autostart.md

커뮤니티에서 관리하는 네이티브 Windows 설정 방법은 @markwang2658/hermes-windows-native-guide (동반 설정 리포지토리: @markwang2658/hermes-windows-native)에 문서화되어 있습니다. #1952 이슈의 커뮤니티 보고 사항:

메모리: 커뮤니티 측정 결과 네이티브는 약 330 MB, WSL2+Docker 사용 시 약 1080 MB (구성 환경에 따라 다름).
작동 항목: 채팅, 워크스페이스 브라우저(workspace browser), 세션 관리, 모든 테마.
알려진 제한 사항: 워크스페이스 브라우저에 일부 POSIX 스타일의 파일 경로가 나타날 수 있음; bash를 가정하는 에이전트 도구(agent tools)는 네이티브 환경에서 작동하지 않을 수 있음.
네이티브 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/bin/python, ELF)은 네이티브 Windows Python에서 호출할 수 없으므로, 위의 네이티브 설정을 사용하세요. 전체 bootstrap.py와 Linux 런타임(runtime)을 사용하고 싶다면 WSL2를 병렬 설치로 유지하는 것이 유용합니다.

설치 후에도 프로바이더(provider) 설정이 완료되지 않은 경우, 온보딩 마법사는 브라우저 내에서 전체 CLI 설정을 복제하려고 시도하는 대신 hermes model을 사용하여 설정을 완료하도록 안내할 것입니다.
마법사 단계별 안내, 프로바이더 선택, 로컬 모델 서버 Base URL 및 안전한 재실행에 대해서는 docs/onboarding.md를 참조하세요.

AI 어시스턴트가 설치, 재설치, 부트스트랩, 프로바이더 설정 또는 첫 실행 지원을 돕고 있다면, 명령을 실행하거나 로그를 조사하기 전에 docs/onboarding-agent-checklist.md를 읽도록 하세요.

• SSE (Server-Sent Events)를 통한 스트리밍 응답 (토큰이 생성되는 즉시 표시)
• 멀티 프로바이더 (Multi-provider) 모델 지원 -- 모든 Hermes API 제공업체 (OpenAI, Anthropic, Google, DeepSeek, Nous Portal, OpenRouter, MiniMax, Xiaomi MiMo, Z.AI) 지원; 설정된 키를 기반으로 모델 드롭다운 목록이 동적으로 생성됨
• 메시지 처리 중 새로운 메시지 전송 -- 자동으로 큐(Queue)에 추가됨
• 과거의 사용자 메시지를 인라인(inline)에서 수정하고 해당 시점부터 다시 생성
• 클릭 한 번으로 마지막 어시스턴트 응답 재시도
• 컴포저(composer) 하단에서 실행 중인 작업 직접 취소 (전송 버튼 옆의 중지 버튼)
• 인라인 도구 호출(Tool call) 카드 -- 각 카드는 도구 이름, 인자(args), 결과 스니펫을 표시; 멀티 도구 턴을 위한 전체 확장/축소 토글 제공
• 서브에이전트 위임(Subagent delegation) 카드 -- 자식 에이전트의 활동을 별도의 아이콘과 들여쓰기된 테두리로 표시
• 인라인 Mermaid 다이어그램 렌더링 (플로우차트, 시퀀스 다이어그램, 간트 차트)
• 사고/추론(Thinking/reasoning) 표시 -- Claude의 확장된 사고(extended thinking) 및 o3 추론 블록을 위한 접이식 골드 테마 카드
• 위험한 셸(shell) 명령에 대한 승인 카드 (한 번 허용 / 세션 동안 허용 / 항상 허용 / 거부)
• 네트워크 일시 오류 시 SSE 자동 재연결 (SSH 터널 탄력성 확보)
• 파일 첨부 파일은 페이지 새로고침 시에도 유지되며, 기본적으로 활성 워크스페이스 외부의 다음 경로에 저장됨 (~/.hermes/webui/attachments/<session_id>/ 또는 설정 시 HERMES_WEBUI_ATTACHMENT_DIR/<session_id>/)
• 메시지 타임스탬프 (각 메시지 옆에 HH:MM 표시, 호버 시 전체 날짜 표시)

세션별 드롭다운 메뉴 — 고정(pin), 프로젝트로 이동(move to project), 보관(archive), 복제(duplicate), 삭제(delete)

• 세션을 사이드바 상단에 고정/즐겨찾기 (금색 표시기)

• 세션 보관 (삭제하지 않고 숨기기, 토글로 표시 가능)

• 세션 프로젝트 -- 세션 정리를 위한 색상이 지정된 이름 있는 그룹

• 세션 태그 -- 제목에 #태그를 추가하여 색상 칩 생성 및 클릭하여 필터링

• 사이드바에 오늘 / 어제 / 이전 항목으로 그룹화 (접이식 날짜 그룹)

• Markdown 대화 기록 다운로드, 전체 JSON 내보내기, 또는 JSON에서 가져오기

• 페이지 새로고침 및 SSH 터널 재연결 시에도 세션 유지

• 브라우저 탭 제목에 활성 세션 이름 반영

• CLI 세션 브릿지 (CLI session bridge) -- hermes-agent의 SQLite 저장소에 있는 CLI 세션이 금색 "cli" 배지와 함께 사이드바에 표시됩니다. 클릭하면 전체 기록과 함께 가져오며 정상적으로 답변할 수 있습니다.

• 토큰/비용 표시 -- 대화당 입력 토큰(input tokens), 출력 토큰(output tokens), 예상 비용 표시 (설정 또는 /usage 명령어로 토글 가능)

• 확장/축소가 가능한 디렉토리 트리 (한 번 클릭 시 토글, 더블 클릭 시 이동)

• 클릭 가능한 경로 세그먼트가 포함된 브레드크럼(Breadcrumb) 네비게이션

• 텍스트, 코드, Markdown(렌더링됨) 및 이미지 인라인 미리보기

• workspace://path/to/file 형식을 사용하는 채팅 링크

• 파일을 오른쪽 미리보기 창에서 열기 - 파일 편집, 생성, 삭제 및 이름 변경; 폴더 생성

• 바이너리 파일 다운로드 (서버에서 자동 감지)

• 디렉토리 이동 시 파일 미리보기 자동 종료 (저장되지 않은 편집에 대한 보호 기능 포함)

• Git 감지 -- 워크스페이스 헤더에 브랜치 이름 및 수정된 파일(dirty file) 수 배지 표시

• 오른쪽 패널은 드래그로 크기 조절 가능

• 구문 강조(Syntax highlighting)가 적용된 코드 미리보기 (Prism.js)

• 컴포저(composer) 내 마이크 버튼 (Web Speech API)

• 탭하여 녹음, 다시 탭하거나 전송하여 중지

• 텍스트 영역(textarea)에 실시간 중간 전사(interim transcription) 표시

• 약 2초간 침묵 시 자동 중지

• 기존 텍스트 영역 콘텐츠에 추가 (교체하지 않음)

• 브라우저가 Web Speech API를 지원하지 않는 경우 숨김 (Chrome, Edge, Safari)

• **작성창 하단 (composer footer)**의 프로필 칩 -- 게이트웨이 상태(gateway status)와 모델 정보가 포함된 모든 프로필을 보여주는 드롭다운

• 게이트웨이 상태 표시 점 (초록색 = 실행 중), 모델 정보, 프로필당 스킬(skill) 개수

• 프로필 관리 패널 -- 사이드바에서 프로필 생성, 전환 및 삭제

• 생성 시 활성 프로필로부터 설정(config) 복제

• 생성 시 선택 사항인 사용자 정의 엔드포인트(custom endpoint) 필드 -- Base URL 및 API 키가 프로필의 config.yaml에 기록됨