Desktop 앱

기준일: 2026-08-02
난이도: 입문
공식 기준: Desktop App, Installation, Desktop Plugin SDK

Hermes Desktop은 CLI·Gateway와 같은 에이전트를 쓰는 네이티브 앱입니다. 별도 계정이나 별도 설정이 아니라 설정, API key, 세션, 스킬, 메모리를 그대로 공유합니다. 한쪽에서 바꾼 내용은 다른 표면에도 그대로 나타납니다. macOS, Windows, Linux에서 동작합니다.

핵심 개념

개념	설명
공유 상태	config·API key·세션·스킬·메모리를 CLI/Gateway와 공유
HERMES_HOME	기본 ~/.hermes. 로컬 모드에서 앱이 이 아래 백엔드를 직접 관리
연결 모드	로컬(기본) / 원격 gateway / Hermes Cloud 중 선택
프로필별 연결	프로필마다 다른 백엔드를 동시에 사용 가능
Desktop plugin	$HERMES_HOME/desktop-plugins/<id>/plugin.js (ESM, 핫 리로드)

CLI를 이미 쓰고 있다면 설치를 새로 할 필요가 없습니다. hermes desktop 한 번이면 기존 설정을 그대로 재사용합니다.

선택 기준

상황	권장 연결 모드
개인 노트북에서 혼자 사용	로컬 — 앱이 백엔드를 알아서 관리
서버에 상시 띄운 에이전트에 붙기	원격 gateway — hermes serve를 별도로 유지해야 함
팀 계정 기반 운영	Hermes Cloud — 로그인하면 에이전트 자동 검색
GUI 없이 터미널만	Desktop 대신 CLI/TUI

원격 모드에서 Desktop 앱은 원격 hermes serve를 대신 띄워주지 않습니다. systemd, tmux 같은 프로세스 매니저로 직접 유지해야 합니다.

실습

설치와 실행

이미 Hermes CLI가 있다면 그대로 실행합니다.

hermes desktop

첫 실행은 workspace Node 의존성을 설치하고 Electron 앱을 빌드한 뒤 띄웁니다. 처음 한 번은 시간이 걸립니다.

CLI가 없는 상태라면 공식 사이트에서 Desktop installer를 받아 설치하면 CLI와 GUI가 함께 설치됩니다.

빌드 동작을 제어하는 플래그입니다.

hermes desktop --skip-build        # 빌드 생략, 기존 앱 실행
hermes desktop --force-build       # 전체 재빌드
hermes desktop --build-only        # 빌드만 하고 실행 안 함
hermes desktop --cwd ~/projects/x  # 초기 프로젝트 디렉터리 지정
hermes desktop --ignore-existing   # PATH의 hermes CLI 무시

원격 gateway에 연결

서버 쪽에서 gateway를 띄워둡니다. 인증 없이 열지 않습니다.

# ~/.hermes/.env
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password

앱에서는 Settings → Gateway → Connection mode → Remote gateway로 접속 정보를 넣습니다.

username/password는 신뢰할 수 있는 네트워크 전용입니다. 인터넷에 노출되는 백엔드라면 OAuth를 씁니다.

hermes dashboard register

주요 화면

영역	내용
Chat	스트리밍 응답 + 도구 실행 실시간 표시, 파일 드래그앤드롭, 우측 미리보기 레일
File browser	로컬 Git 저장소 자동 검색, 파일 미리보기
Git review	변경 리뷰 페인, worktree로 브랜치 병렬 작업
Memory Graph	학습된 스킬·메모리를 노드 맵으로 시각화
Artifacts	이미지·파일·링크 갤러리
Terminal	앱 안에서 터미널 실행
Settings	provider·API key·모델·reasoning effort·MCP 서버를 GUI로 관리

상태바에는 세션별 YOLO 토글(위험 명령 승인 우회)과 컨텍스트 사용량 미터가 있습니다. YOLO는 승인 절차를 건너뛰므로 무엇을 끄는지 알고 켜야 합니다.

단축키

키	동작
Cmd/Ctrl+K 또는 Cmd/Ctrl+P	커맨드 팔레트
Cmd/Ctrl+N	새 세션
Cmd/Ctrl+T / Ctrl+Tab	새 탭 / 세션 순환
Cmd/Ctrl+W / Cmd/Ctrl+Shift+T	탭 닫기 / 마지막 탭 복원
Cmd/Ctrl+G	Git 리뷰 페인
Cmd/Ctrl+Shift+B	Git worktree 생성
Cmd/Ctrl+B / Cmd/Ctrl+J	좌측 / 우측 사이드바
Cmd/Ctrl+F	페이지 내 검색
Cmd/Ctrl+Shift+F	세션 ID 검색
Ctrl+` / Ctrl+Shift+`	터미널 표시 / 추가 터미널
Ctrl/Cmd+Shift+Space	Quick Entry (전역, 변경 가능)
Cmd/Ctrl+/	단축키 패널
Shift+X	라이트/다크 전환

플러그인으로 확장

플러그인은 ESM 파일 하나입니다.

$HERMES_HOME/desktop-plugins/<id>/plugin.js

페인, 페이지, 사이드바 항목, 상태바 아이템, 팔레트 명령, 키바인드, 테마를 하나의 SDK로 등록합니다. 저장하면 수 초 안에 핫 리로드됩니다.

업데이트와 제거

업데이트는 백그라운드에서 확인하고 준비되면 원클릭으로 적용합니다. CLI의 수동 업데이트 절차도 그대로 동작합니다.

제거는 Settings → About → Danger zone에서 범위를 고릅니다.

hermes uninstall --gui     # GUI만 제거, 에이전트와 데이터 유지
hermes uninstall           # GUI + 에이전트 제거, 설정과 대화 유지
hermes uninstall --full    # 전부 제거

트러블슈팅

부팅 실패는 먼저 로그를 봅니다.

hermes logs gui -f
# 또는 직접: $HERMES_HOME/logs/desktop.log

증상	조치
첫 실행 설정이 꼬임	rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
Python 환경 손상	rm -rf "$HOME/.hermes/hermes-agent/venv"
macOS 마이크 권한 프롬프트가 안 뜸	tccutil reset Microphone com.nousresearch.hermes
Electron 다운로드가 멈춤	ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

macOS의 TCC 권한(마이크·화면 등)은 코드 서명 신원에 묶입니다. 로컬에서 재빌드하면 기본적으로 ad-hoc 서명이라 재빌드마다 권한이 초기화될 수 있습니다. 고정 자체 서명 인증서를 지정하면 유지됩니다.

hermes config set desktop.macos_signing_identity "Hermes Local Signing"

대화 중간에 모델을 바꾸면 프롬프트 캐시가 초기화됩니다. 긴 대화에서는 추론 비용이 올라가므로 모델은 가급적 세션 시작 시점에 정합니다.

Hermes에 입력할 프롬프트

내 Hermes 사용 패턴을 보고 Desktop 연결 모드를 골라줘.
로컬 관리형 백엔드 / 원격 gateway / Hermes Cloud 중 어떤 것이 맞는지,
그 선택에서 내가 직접 유지해야 하는 프로세스와 인증 설정이 무엇인지 정리해줘.

원격 노출을 검토할 때:

Hermes Desktop을 원격 gateway 모드로 쓰려고 해.
basic auth와 OAuth 중 어느 쪽이 필요한지 판단해주고,
서버에서 hermes serve를 상시 유지하는 방법과
공개 인터넷에 노출될 때 막아야 할 항목을 체크리스트로 만들어줘.

체크리스트

• CLI가 이미 있다면 재설치 대신 hermes desktop으로 시작했다.
• 연결 모드(로컬 / 원격 gateway / Cloud)를 의도적으로 골랐다.
• 원격 모드라면 hermes serve를 별도 프로세스 매니저로 유지하고 있다.
• 인터넷 노출 백엔드에 basic auth만 쓰지 않고 OAuth를 구성했다.
• YOLO 토글이 승인 절차를 우회한다는 점을 알고 켠다.
• macOS에서 재빌드한다면 서명 신원을 고정해 권한 초기화를 막았다.
• 긴 대화 중 모델 전환이 캐시를 초기화한다는 점을 고려했다.

다음 단계

• Web Dashboard와 프로필에서 브라우저 관리 표면과 프로필 분리를 확인합니다.
• 세션과 프로필에서 세션 운영 기준을 정리합니다.
• 체크포인트와 Worktree에서 Git 리뷰 페인이 쓰는 worktree 개념을 확인합니다.
• 보안과 승인에서 YOLO 토글이 우회하는 승인 체계를 확인합니다.