hermes-webui 딥다이브
— 빌드 도구 0개로 만든 "내 서버 위 AI 에이전트" 웹 UI

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

조금 더 풀어볼게요. Hermes Agent는 "내 서버에 상주하면서, 배운 것을 기억하고, 오래 켜둘수록 똑똑해지는" 자율 에이전트입니다. 원래는 터미널(CLI)이나 메신저로 쓰죠. 그런데 터미널은 폰에서 쓰기 불편하고, 도구 호출 결과나 파일을 눈으로 보기도 어렵습니다. hermes-webui는 바로 그 CLI 경험을 왼쪽 세션 · 가운데 채팅 · 오른쪽 파일 3분할 웹 화면으로 옮겨, "터미널로 하던 거의 모든 것"을 마우스와 손가락으로 하게 해줍니다.

흥미로운 점은 만든 방식입니다. 보통 이런 채팅 UI는 React 같은 프레임워크로 짓는데, 이 레포는 파이썬 표준 라이브러리 HTTP 서버 + 순수 자바스크립트만 씁니다. 빌드도, 번들러도 없어요. 덕분에 python3 bootstrap.py 한 줄이면 뜨고, 코드를 고치면 새로고침만 하면 바로 반영됩니다.

2왜 주목받는가

트렌딩 이유 · 경쟁 도구 대비 강점 · 냉정하게 보기.

2026년 들어 "항상 켜져 있고, 내 서버에서 돌고, 기억을 가진" 자율 에이전트가 한 흐름을 이뤘습니다. Claude Code·Codex·OpenCode·OpenClaw가 대표적이죠. Hermes는 이 경쟁에서 "파이썬 생태계 + 완전 셀프호스팅 + 자동 기억"을 내세웁니다. hermes-webui는 그 에이전트에 폰에서도 쓰는 예쁜 웹 얼굴을 붙였다는 점에서 화제가 됐어요. README가 직접 정리한 비교는 이렇습니다.

이 표에서 webui 입장의 진짜 매력은 마지막 줄들입니다. SSE 스트리밍(글자가 타이핑되듯 흐르는 응답), 도구 호출 카드(에이전트가 어떤 도구를 어떤 인자로 불렀는지 펼쳐 보기), 워크스페이스 파일 브라우저(에이전트가 만든 파일을 바로 미리보기·편집), 모바일 반응형(폰에서 햄버거 메뉴로 그대로) — 터미널로는 어려운 것들을 웹의 강점으로 풀어줍니다.

3기술 스택 전체 지도

백엔드 · 프론트엔드 · 인프라를 떠받치는 도구들 한눈에.

이 프로젝트의 스택은 한마디로 "있을 건 다 있는데, 무거운 건 하나도 없다"입니다. 진짜 무게(LLM·머신러닝 라이브러리)는 옆집(Hermes Agent venv)에 다 떠넘기고, webui는 표준 라이브러리만으로 살림을 차렸어요. 레이어별로 봅시다.

백엔드 (Python)

프론트엔드 (바닐라 JS)

인프라 / 배포

4아키텍처 심화 분석

브라우저에서 친 한 마디가 LLM 응답으로 돌아오기까지.

먼저 숲(전체 그림)입니다. 핵심은 "server.py는 교통정리만, 진짜 일은 api/ 모듈이, 진짜 두뇌는 에이전트가"라는 3단 구조예요. 브라우저 ↔ 얇은 HTTP 껍데기 ↔ 두꺼운 api 로직 ↔ 같은 프로세스에 import된 Hermes 에이전트 ↔ LLM 제공자.

이제 나무(흐름 한 줄기)를 따라가 봅시다. 사용자가 메시지를 보내 응답이 흐르기까지의 해피 패스입니다.

① 요청 진입 + 인증 — 모든 요청은 server.py의 Handler로 들어옵니다. 쓰기 요청(POST/PUT/PATCH/DELETE)은 공통 래퍼 _handle_write를 거쳐 쿠키에서 프로파일을 꺼내고, 인증을 확인한 뒤 api/routes.py로 위임합니다. server.py 자체엔 비즈니스 로직이 거의 없어요.

def do_POST(self): self._handle_write(handle_post)

def _handle_write(self, route_func):
    cookie_profile = get_profile_cookie(self)
    if cookie_profile: set_request_profile(cookie_profile)  # 요청별 프로파일
    try:
        parsed = urlparse(self.path)
        if not check_auth(self, parsed): return        # 인증 미들웨어
        result = route_func(self, parsed)              # api/routes.py로 위임
        if result is False: return j(self, {'error':'not found'}, status=404)
    finally:
        clear_request_profile()

② 에이전트 실행 + 스트리밍 — 채팅이면 api/streaming.py의 run_agent가 import된 Hermes 에이전트를 돌립니다. 에이전트가 토큰·도구호출·추론을 내놓을 때마다 SSE 이벤트로 즉시 브라우저에 밀어 보내요. 사용자가 Stop을 누르면 취소 신호가 전달됩니다.

③ 브라우저 렌더 — 프론트의 messages.js가 EventSource로 토큰을 받아, 화면을 requestAnimationFrame 주기로 부드럽게 갱신합니다. 도구 호출은 접고 펼치는 카드로, 코드는 Prism으로, 다이어그램은 Mermaid로 그려집니다.

기억해둘 핵심 설계 패턴 6가지

5디렉토리 구조 해부

어느 파일이 무슨 일을 하는가.

구조의 메시지는 분명합니다. 화면(static)과 로직(api)이 깔끔히 분리되고, 진입점(server.py)은 얇습니다. 큰 파일 순서(routes 9.8k → ui.js 7.2k → panels.js 6.5k → streaming 4.4k → config 4.1k)만 봐도 "라우팅·UI·실시간 스트리밍"이 이 앱의 무게 중심임을 읽을 수 있어요. 상태는 레포 밖 ~/.hermes/webui/에 두어, 코드를 업데이트해도 내 세션·설정이 날아가지 않습니다.

6학습 포인트 (기술별)

이 레포에서 실제로 뽑아 배울 것 + 곧바로 해볼 실습 아이디어.

① 프레임워크 없이 만드는 HTTP 서버

가장 큰 배움입니다. 다들 Flask·FastAPI부터 배우지만, 그 밑에 깔린 표준 라이브러리 http.server를 직접 다뤄보면 "프레임워크가 대신 해주던 일"이 보입니다. 이 레포는 ThreadingHTTPServer로 연결마다 스레드를 띄우고, BaseHTTPRequestHandler를 상속해 do_GET/do_POST를 직접 구현하며, HTTP/1.1 keep-alive와 TCP_NODELAY·SO_KEEPALIVE 소켓 옵션까지 손으로 켭니다.

② SSE로 LLM 토큰 스트리밍하기

ChatGPT식 "타닥타닥" 응답의 정체가 SSE입니다. 서버가 Content-Type: text/event-stream으로 응답을 열어두고 data: ...\n\n를 계속 흘려보내면, 브라우저의 EventSource가 받아 화면에 붙입니다. 끊겨도 자동 재연결이 표준 동작이라, 불안정한 터널에서도 견딥니다.

③ 빌드 없는 바닐라 JS 프론트엔드

5만 줄이 넘는 프론트를 React 없이 운영한다는 건 흥미로운 사례 연구입니다. 장점은 빌드 0·즉시 반영·디버깅 단순함, 대가는 타입 안정성·컴포넌트 재사용·상태관리의 부재입니다. ui.js가 어떻게 DOM 헬퍼와 마크다운 렌더러를 직접 굴리는지 보면 "프레임워크가 왜 등장했는지"를 거꾸로 이해하게 됩니다.

④ 셀프호스팅 & 안전한 원격 접근

"내 서버에서 돌리고 폰에서 본다"를 안전하게 하는 두 정석을 배웁니다. SSH 터널(ssh -N -L로 로컬 포트를 원격 loopback에 연결)과 Tailscale(WireGuard 기반 메시 VPN으로 포트 개방 없이 같은 사설망). 기본 바인딩을 loopback으로 두고, 외부 노출 시 비밀번호를 강제하는 "안전 우선" 운영 철학도 함께 익히게 됩니다.

⑤ MCP 서버 만들기 + 보안 기초

mcp_server.py는 "내 앱의 기능을 다른 AI가 호출하는 도구로 노출"하는 MCP 서버의 깔끔한 예제입니다. Tool 정의 + 핸들러 매핑 + stdio 서버라는 표준 골격을 100% 보여줘요. 더불어 HMAC 서명 쿠키·CSP·입력 검증(색상 정규식, 길이 제한) 같은 실전 보안 패턴도 함께 읽을 수 있습니다.

7하드웨어 / 시스템 요구사항

webui 자체는 가볍다 — 무거운 건 에이전트와 모델 쪽.

중요한 구분: hermes-webui 자체는 거의 자원을 안 먹습니다. 표준 라이브러리 HTTP 서버일 뿐이니까요. 실제 비용·부하는 ① 옆에서 도는 Hermes Agent와 ② 그 에이전트가 호출하는 LLM(클라우드 API 또는 로컬 모델)에서 발생합니다.

8직접 해볼 수 있는 실습 과제

난이도별로 손을 움직여 보는 5단계.

9관련 기술 심화 학습 로드맵

이 레포를 제대로 소화하기 위한 4주 학습 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub 저장소: nesquena/hermes-webui
• 프로젝트 홈: get-hermes.ai
• 두뇌(에이전트): Hermes Agent — Nous Research
• SSE 표준: MDN — Server-Sent Events
• 파이썬 HTTP 서버: docs.python.org — http.server
• MCP 규약: Model Context Protocol
• 안전 원격 접속: Tailscale
• 비교용 경쟁 도구: Claude Code · Codex