설치 마법사, 스트리밍 채팅, 22개 슬래시 커맨드, 16개 메시징 게이트웨이, 메모리·스킬·페르소나·크론 잡 관리까지 한 화면에서 처리한다.
Hermes Agent는 본체가 Python 패키지로, curl ... | bash로 설치한 뒤 터미널에서 hermes 명령으로 굴린다. 많은 사람들에게 친숙한 흐름이지만, 비개발자에게는 진입 장벽이 높다. hermes-desktop은 그 사이를 메우는 "공식 GUI 포장지" 같은 존재다. 내부적으로는 로컬에 떠 있는 http://127.0.0.1:8642 Hermes API 서버에 SSE 스트리밍으로 붙어서 토큰·툴 진행 상황을 실시간으로 그려준다.
Hermes Agent가 엔진이라면, hermes-desktop은 그 엔진을 감싼 자동차의 운전석이다. 엔진(=백엔드) 자체는 터미널 명령으로도 돌릴 수 있지만, 핸들·계기판·내비게이션 없이는 일상적으로 운전하기 어렵다. 이 데스크탑 앱은 그 운전석을 통째로 제공한다.
2026년 트렌딩의 큰 흐름은 "내 LLM을 내 머신에서 굴리고 싶다"이다. Cursor·Claude Code·Codex CLI 같은 코딩 에이전트가 폭발한 뒤, 그 다음 자연스러운 질문이 따라왔다 — "코딩 이외의 일상 업무는?". Hermes Agent는 메신저·스케줄·메모리·페르소나를 모두 묶어 "개인용 자기개선형 비서"를 표방하고, hermes-desktop은 그 비서의 얼굴 역할을 한다.
hermes model 등 명령 암기Agents 화면에서 CRUDLM Studio·Ollama Desktop은 "모델 자체"를 굴리는 데 집중하고 에이전트 행동 루프는 외부다. Open WebUI는 웹 UI이고 메시징 플랫폼 연동이 약하다. hermes-desktop은 본체(Hermes Agent)에 메모리·스킬·페르소나·메신저 16종이 이미 결합돼 있고, GUI는 그 컨트롤 패널 역할을 한다. "AI 비서를 내 컴퓨터에 정착시키기" 카테고리에서는 가장 통합도가 높다.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 셸 | Electron 39 | 크로스 플랫폼 데스크탑 컨테이너. Chromium + Node.js를 하나의 바이너리로 묶는다. |
| UI 프레임워크 | React 19.2 | 최신 React. Server Components/Actions 등은 데스크탑이라 일부만 사용. |
| 언어 | TypeScript 5.9 | main / preload / renderer 3개 프로세스 모두 TS. tsconfig.node.json, tsconfig.web.json로 분리. |
| 스타일 | Tailwind CSS 4 (+@tailwindcss/vite) | 유틸리티 클래스 기반. CSS 6.3%는 대부분 Tailwind 생성물. |
| 빌드 / Dev | Vite 7 + electron-vite 5 | HMR 가능한 Electron 개발 환경. 3개 프로세스를 한 번에 빌드. |
| 로컬 DB | better-sqlite3 12 | SQLite + FTS5 풀텍스트 검색. 세션 히스토리 저장. |
| 마크다운 | react-markdown + remark-gfm | 채팅 메시지의 마크다운/표/체크박스 렌더링. |
| 코드 하이라이트 | react-syntax-highlighter | 코드 블록 채색. |
| 아이콘 | lucide-react | 가벼운 SVG 아이콘 셋. |
| 국제화 | i18next + react-i18next | 현재 영어 로케일만 포함, 커뮤니티 번역 대기. |
| 테스트 | Vitest 4 + @testing-library/react + jsdom | SSE 파서, IPC 핸들러, preload API, 설치 유틸리티 단위 테스트. |
| 패키징 | electron-builder 26 + electron-updater | Win/macOS/Linux/RPM 빌드 + 자동 업데이트. |
| 린트/포맷 | ESLint 9 + Prettier + Husky | 커밋 훅에서 자동 검사. |
2026년 5월 현재 가장 최신 메이저 버전들을 깔끔하게 조합한 사례다. 특히 Tailwind 4 + @tailwindcss/vite 플러그인 조합은 PostCSS 빌드 없이 Vite가 바로 처리하는 신식이라, Tailwind 마이그레이션 공부 자료로도 유용하다.
hermes-desktop은 자체 백엔드가 없다. 대신 NousResearch/hermes-agent를 로컬에 설치하고 그 HTTP 서버에 붙는다.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 언어 | Python 82% + TypeScript 14% | 핵심 에이전트 루프는 Python, 웹/TUI 일부가 TS. |
| HTTP | 로컬 서버 127.0.0.1:8642 | SSE(Server-Sent Events)로 토큰 스트리밍. |
| 의존성 매니저 | uv + Python 3.11+ | Astral의 차세대 pip. 빠르고 락파일 기반. |
| 패키징 | pyproject.toml + Dockerfile + flake.nix | pip 설치, Docker, Nix 셸 모두 지원. |
| 메모리 | Honcho, Hindsight, Mem0, RetainDB, Supermemory, ByteRover 등 플러그인 | "사용자 모델" 누적용 외부 메모리 백엔드. |
| 검색 | Exa, Tavily, Parallel API, Firecrawl | 웹 검색·크롤링 툴 통합. |
| 스케줄러 | 자체 cron 엔진 (~/.hermes/cron/jobs.json) | 분/시간/일/주/커스텀 cron 표현식. |
~/.hermes/ — Hermes Agent 설치 루트 (윈도우는 %LOCALAPPDATA%\hermes).~/.hermes/.env — API 키.~/.hermes/config.yaml — 프로바이더·모델 설정.~/.hermes/profiles/ — 프로파일별 격리 디렉토리.~/.hermes/state.db — 세션 히스토리 SQLite DB (better-sqlite3 + FTS5 풀텍스트 검색이 여기서 작동).~/.hermes/cron/jobs.json — 크론 잡 정의.모든 Electron 앱이 그렇듯 hermes-desktop은 세 개의 분리된 프로세스로 구성된다. 보안과 안정성을 위해 강제된 구조로, 한 번 이해하면 다른 Electron 앱(VS Code, Discord, Slack 등)도 똑같이 읽을 수 있다.
비즈니스 로직(LLM 호출, 메모리 관리, 스킬 실행, 메신저 라우팅)은 모두 Hermes Agent 백엔드에 있고, 데스크탑은 입출력과 설정 관리만 담당한다. 이 분리 덕분에 같은 백엔드를 텔레그램·디스코드 봇으로도, 데스크탑 GUI로도 동시에 쓸 수 있다.
Main 프로세스가 127.0.0.1:8642에 SSE로 붙어 token / tool_call / tool_result 이벤트를 받고, IPC로 Renderer에 그대로 흘려보낸다. Renderer는 React state에 토큰을 누적해 한 글자씩 그리는 "타자기 효과"를 만든다.
첫 실행 시 사용자가 local(이 컴퓨터에 백엔드 설치)과 remote(별도 서버의 Hermes에 URL+API key로 접속)를 고른다. 같은 SSE 프로토콜이라 UI 코드는 분기 없이 동작한다 — VPS에 Hermes를 띄우고 노트북에서 붙는 패턴이 가능하다.
모든 대화는 ~/.hermes/state.db에 저장된다. 데스크탑은 better-sqlite3으로 동일한 파일을 읽어 FTS5 인덱스에 직접 쿼리한다. "한 달 전에 OAuth 디버깅한 대화 어디 있더라?"가 1초 안에 해결된다.
Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email IMAP/SMTP, SMS(Twilio/Vonage), iMessage(BlueBubbles), DingTalk, Feishu, WeCom, WeChat, Webhooks, Home Assistant — 모두 같은 "Gateway" 추상화를 통해 Hermes 백엔드에 메시지를 흘려넣는다. 데스크탑 GUI는 각 플랫폼의 토큰만 받아서 백엔드에 저장한다.
Renderer는 샌드박스 모드로 돌아 Node.js API를 직접 호출할 수 없다. 파일 시스템·자식 프로세스 spawn 등은 모두 preload 스크립트가 contextBridge.exposeInMainWorld('api', ...)로 노출한 제한된 API를 통해 Main에 IPC 요청을 보낸다. preload의 표면적이 곧 보안 경계라서 테스트(tests/preload)에 공을 들인다.
electron.vite.config.ts — Electron 멀티 프로세스 빌드의 정답에 가까운 설정. 사본 떠두면 다른 Electron 프로젝트 시작이 쉽다.
skills-lock.json — Anthropic agentskills.io 표준 호환 lock 파일. Skill 버전 관리의 실전 예시.
tsconfig.node.json + tsconfig.web.json 분리 — Node 환경과 DOM 환경의 타입을 깨끗하게 격리하는 모범 사례.
.husky/pre-commit — lint-staged 없이 husky 단독으로 커밋 시점 검사. Husky 9+ 방식.
Main / Preload / Renderer 3-프로세스 모델, contextBridge로 안전한 API 노출, IPC(ipcMain.handle ↔ ipcRenderer.invoke) 패턴. electron-vite로 HMR 가능한 dev 환경 구축.
실습 — npm run dev로 띄운 뒤 Renderer 코드 수정 → 즉시 반영되는지 확인하고, Main 프로세스 코드를 수정한 뒤에는 앱 재시작이 필요함을 체감해 본다.
React 19에서 추가된 use() 훅, Actions, 자동 batching 강화 등을 데스크탑 환경에서 실전 적용한 사례.
실습 — src/renderer/hooks/의 커스텀 훅을 따라 만들어 보고, SSE 스트림을 받는 useStreamingChat 같은 훅을 직접 구현해 본다.
WebSocket보다 가벼운 단방향 스트리밍. fetch + ReadableStream으로 한 글자씩 받는 방법, 토큰 청크를 React state에 누적해 타자기 효과 만들기.
실습 — ChatGPT/Claude API를 SSE 모드로 호출해 토큰 단위로 콘솔에 찍는 50줄짜리 스크립트부터 만들어 본다.
비동기 sqlite3와 달리 동기 API라 Electron Main에서 다루기 쉽다. CREATE VIRTUAL TABLE ... USING fts5로 한국어 포함 풀텍스트 검색 가능.
실습 — 메모장 앱을 만들어 모든 노트 본문을 FTS5 인덱스에 넣고, MATCH 쿼리로 1초 안에 검색되는지 확인.
PostCSS 없이 @tailwindcss/vite로 통합. @theme 디렉티브로 CSS 변수 기반 테마링. v3 대비 빌드 속도 향상이 체감된다.
실습 — 기존 Tailwind v3 프로젝트를 v4로 마이그레이션해 보고 빌드 시간 차이를 측정.
Jest 대체. ESM 친화적이고 빠르다. tests/에서 SSE 파서, IPC 핸들러, preload 표면, 설치 유틸리티를 어떻게 격리해 테스트하는지 확인할 수 있다.
실습 — 임의의 SSE 응답 청크를 입력하면 토큰 배열을 뱉는 파서 함수를 TDD로 구현.
electron-builder.yml에서 Win/Mac/Linux/RPM 4개 타깃 동시 설정, electron-updater로 차등 업데이트.
실습 — 자기 Hello World Electron 앱에 build:win, build:mac, build:linux를 모두 적용해 본다.
"기능이 많은 AI를 어떻게 GUI로 풀어 놓을 것인가"의 실전 답안. 채팅·세션·툴·스킬·메모리·페르소나·스케줄·게이트웨이가 각각 별도 화면으로 분리된 IA(정보구조)를 참고할 수 있다.
실습 — 자기가 쓰는 AI 비서의 기능 목록을 똑같이 12개 사이드바로 풀어 본다.
| 구분 | 요구사항 | 비고 |
|---|---|---|
| OS | Windows 10/11, macOS 11+, Linux (Ubuntu 22.04+, Fedora 등) | WSL2도 지원 — 다만 설치 스크립트 sudo 이슈 있음(#109) |
| RAM | 최소 4GB, 권장 8GB+ | 로컬 LLM(Ollama 등)을 같이 굴리면 16GB+ 필요 |
| 디스크 | 2GB(앱) + 5~50GB(Hermes Agent + 모델 캐시) | 로컬 모델 사용 시 디스크 부담 큼 |
| 네트워크 | 설치 시 필수(uv, Python, ripgrep, ffmpeg 다운로드) | 로컬 모델만 쓰면 그 후엔 오프라인 가능 |
| 의존성 | Node.js 20+, npm, Git, Python 3.11+ | 설치 마법사가 거의 다 해결 |
| GPU | 선택사항 | API 모드면 불필요. Ollama/vLLM 로컬 모델이면 VRAM 8GB+ 권장 |
NOPASSWD 설정) 안내가 있다.--nogpgcheck 필요할 수 있고, auto-update 미지원(재설치로 갱신).릴리스 페이지에서 OS에 맞는 바이너리를 받아 설치 → 첫 화면에서 "Local mode" → 마법사 따라 OpenRouter API 키 입력 → 무료 티어 모델(google/gemma-2-9b-it:free 등) 선택 → "토큰이 한 글자씩 흘러나오는" SSE 스트리밍을 직접 확인.
ollama serve로 띄운 뒤 hermes-desktop의 Providers 화면에서 "Local/Custom" 선택, base URL을 http://localhost:11434/v1로 설정. 동일한 채팅 UX가 완전 오프라인에서 돌아가는 것을 확인.
git clone → npm install → npm run dev. Chat 화면 컴포넌트(src/renderer/components/Chat/)에 자기만의 사이드 패널을 하나 추가해 본다 — 토큰 사용량 그래프를 라이브로 그리는 미니 위젯이 좋은 출발점.
BotFather로 텔레그램 봇 생성 → Gateway 화면에서 토큰 등록 → "내일 오전 9시에 어제 GitHub 활동 요약해서 보내줘"라고 채팅. Schedules 화면에서 cron 잡이 생성됐는지, 실제로 다음날 텔레그램에 메시지가 오는지 확인.
.agents/skills/에 넣어 본 뒤 호출Anthropic agentskills.io 표준의 SKILL.md를 따라 "내 한국어 블로그 스타일로 글 다듬기" 같은 Skill을 작성. YAML frontmatter에 트리거 키워드 명시 → skills-lock.json 갱신 → Skills 화면에서 활성화 → 채팅에서 "이 글 좀 다듬어줘"로 호출되는지 검증.
Hetzner/Vultr 등에 우분투 VPS 생성 → 공식 설치 스크립트 → hermes serve로 백엔드 노출(reverse proxy + HTTPS 권장) → 노트북 hermes-desktop에서 "Remote mode" 선택, URL+API key 입력. 노트북을 닫아도 cron 잡과 메신저 봇이 VPS에서 계속 돌아가는 풀스택 구성 완성.
공식 튜토리얼("Hello World" → "퀵 스타트")을 끝까지 따라하고, Main / Preload / Renderer 분리의 의미를 손에 새긴다. contextBridge로 안전한 API를 노출하는 패턴을 직접 짜본다.
hermes-desktop의 electron.vite.config.ts와 tsconfig.*.json 분리 방식을 그대로 베껴 자기 프로젝트의 보일러플레이트로 만든다. HMR이 Renderer에만 적용되고 Main은 재시작이 필요함을 체감.
OpenAI/Anthropic/OpenRouter의 SSE 응답 포맷을 비교하고, 통합 파서를 만든다. ReadableStream + TextDecoder로 한 글자씩 토큰을 React state에 흘려보내는 훅을 처음부터 작성.
한국어 토크나이저(unicode61 remove_diacritics 2) 옵션을 학습. 100만 행 더미 데이터를 넣고 MATCH 쿼리 응답 시간을 측정. EXPLAIN QUERY PLAN으로 인덱스 활용을 확인.
v3 → v4 변경점(설정 파일 폐지, @theme 도입, JIT 기본화)을 정리. hermes-desktop이 어떻게 CSS 변수와 Tailwind 유틸리티를 함께 쓰는지 분석.
Electron Main 코드의 IPC 핸들러를 jsdom 없이 테스트하는 패턴, preload 표면을 mock해서 Renderer 컴포넌트를 테스트하는 패턴. tests/ 디렉토리를 읽으며 따라간다.
코드 사인(macOS Notarization, Windows Code Signing) 비용·절차를 조사, 차등 업데이트(blockmap)의 작동 원리 파악. 자기 앱에 GitHub Releases 기반 자동 업데이트 채널을 붙여 본다.
Python 88%인 본체로 넘어가서 agent/, toolsets.py, cron/을 읽으며 "데스크탑이 어떤 HTTP 엔드포인트들을 호출하는지" 매핑한다. 결국 두 레포가 어떻게 맞물리는지 그림이 그려진다.
ipcMain.handle / ipcRenderer.invoke 짝으로 비동기 호출.window.api.foo() 형태로 접근.text/event-stream MIME으로 토큰을 한 줄씩 흘려보낸다. LLM 응답 스트리밍의 사실상 표준.CREATE VIRTUAL TABLE ... USING fts5로 만들고 MATCH 키워드로 검색.hermes CLI를 제공.* * * * * 5필드(분·시·일·월·요일)로 스케줄을 표현. hermes는 이 위에 "자연어 → cron" 변환 레이어를 얹어 있다..exe, .dmg, .deb, .rpm 등)로 패키징하는 도구.