헤르메스 데스크톱 앱 설치·연결 가이드

지금까지 우리는 헤르메스를 두 가지 방식으로 만나왔습니다. 터미널에서 명령으로 부르는 방식, 그리고 브라우저로 여는 웹 대시보드입니다. 이번에는 세 번째, 손에 잡히는 데스크톱 앱을 깔고 우리 회사에 연결해 봅니다.

중요한 건 새 프로그램이 아니라는 점입니다. 똑같은 코어, 똑같은 직원, 똑같은 설정을 그대로 쓰되, 화면만 네이티브 앱으로 바뀌는 것입니다. 그래서 터미널에서 해둔 작업이 앱에도 그대로 있습니다.

💡 사전 요구사항: 헤르메스 멀티 프로필 가이드에서 MAGMA 팀을 채용해 두셨다는 전제로 설명합니다. 화면별 기능을 더 보고 싶으면 데스크톱 화면·설정 치트시트를 함께 참고하세요.

⚠️ 데스크톱 앱은 헤르메스 0.16.0 이상에서 제공됩니다. 먼저 hermes --version으로 버전을 확인하세요.

시스템 구조 — 표면은 셋, 코어는 하나

설치에 들어가기 전에 큰 그림부터 보겠습니다. 터미널(TUI), 웹 대시보드, 데스크톱 앱은 각각 다른 프로그램이 아닙니다. 하나의 코어에 붙는 세 개의 표면일 뿐입니다.

코어 하나에 config, 키, 세션, 스킬, 기억, 프로필이 모두 들어 있습니다. 어느 표면으로 들어가든 같은 직원, 같은 설정을 만나는 이유입니다. 그래서 표면은 상황에 맞게 바꿔 끼우면 됩니다. 가볍고 빠른 작업은 터미널, 시각적으로 보고 싶을 때는 대시보드나 데스크톱 앱처럼요.

1. 데스크톱 앱 설치

데스크톱 앱은 헤르메스 에이전트의 공식 홈에서 받습니다.

🔗 공식 홈: https://hermes-agent.nousresearch.com

이곳이 헤르메스 에이전트의 공식 홈이자 데스크톱 앱 배포처입니다. 접속하면 INSTALL DESKTOP APP의 다운로드 버튼과, 터미널로 바로 설치하는 INSTALL VIA TERMINAL 명령이 함께 안내됩니다.

설치 방법은 두 가지입니다. 편한 쪽을 고르시면 됩니다.

방법 A. 명령 한 줄 (헤르메스를 이미 설치한 경우)

hermes desktop

이미 설치된 헤르메스와 자동으로 연동됩니다.

방법 B. 설치 파일 받기

위 공식 홈에 접속하면 운영체제에 맞는 다운로드 버튼이 자동으로 표시됩니다. 맥에서 접속하면 macOS용, 윈도우에서 접속하면 Download for Windows로 바뀝니다. 버튼이 한 종류만 보여도 정상이니, 그대로 받아 설치 마법사를 진행하세요.

설치가 끝나고 Launch Hermes로 앱을 처음 열면 경고창이 뜰 수 있습니다. 당황하지 마시고 Use Local Gateway 버튼을 누르면 초기 화면으로 들어갑니다.

💡 두 방법은 서로 자동으로 동기화됩니다. 명령으로 켜도 되고, 설치 파일로 깔아도 됩니다. 첫 실행 때 Python, Git 같은 의존성은 앱이 알아서 준비합니다.

2. 연결 — 맥과 윈도우(WSL)가 다릅니다

여기서부터 운영체제에 따라 길이 갈립니다.

맥 사용자 — 별도 설정 없이 바로 연동

맥은 헤르메스가 이미 맥에 네이티브로 설치되어 있습니다. 그래서 데스크톱 앱도 추가 설정 없이 그 헤르메스에 바로 붙습니다. 게이트웨이를 Local gateway로 두면 로컬에 있는 프로필이 그대로 보입니다. 아래 3번(원격 연결)은 건너뛰고, 그동안 키운 직원들을 바로 쓰시면 됩니다.

💡 맥 사용자는 터미널(TUI)에서 한 작업이 데스크톱 앱에도 동일하게 동기화됩니다. 같은 코어를 보고 있기 때문입니다.

윈도우(WSL) 사용자 — 원격 게이트웨이로 연결

윈도우는 사정이 다릅니다. 우리가 안내해 드린 대로 헤르메스를 WSL(리눅스) 안에 설치하셨기 때문입니다. 그런데 데스크톱 앱은 윈도우 네이티브 프로그램이라, WSL 안의 헤르메스와는 완전히 별개입니다. 앱을 그냥 켜면 WSL의 직원들이 보이지 않습니다.

그래서 데스크톱 앱을 WSL 안의 헤르메스에 원격(Remote)으로 붙여줘야 합니다. WSL에서 대시보드를 띄워두고, 윈도우 앱이 거기에 접속하는 구조입니다.

여기서 세 군데가 막히기 쉽습니다. 순서대로 풀어드리겠습니다.

관문 1 — 주소는 localhost가 아니라 WSL 주소로

윈도우의 localhost로는 WSL에 닿지 않습니다. WSL이 윈도우와 다른 네트워크에 있기 때문입니다. WSL의 실제 주소를 써야 합니다.

• WSL 터미널에서 IP를 확인합니다(보통 172.x.x.x 형태). Tailscale을 쓰신다면 Tailscale 주소(100.x.x.x)가 더 안정적입니다.
• 주소는 https가 아니라 http로 적습니다. 예: http://172.26.x.x:9119

관문 2 — 대시보드를 열기 전에 비밀번호(환경 변수)를 먼저 설정합니다

WSL에서 대시보드를 외부 접속이 가능하도록 0.0.0.0으로 열면, 헤르메스가 안전을 위해 비밀번호를 요구합니다. 그래서 대시보드를 띄우기 전에 인증용 환경 변수 세 개를 먼저 설정해 둬야 합니다. 비밀번호 하나만 정해두면 모든 직원에 같이 쓰입니다.

SECRET 값은 직접 짓지 말고, 난수 생성기로 만들어 붙여넣습니다. WSL 터미널에서 다음을 실행하면 난수가 나옵니다.

openssl rand -base64 32

출력된 난수를 복사해 SECRET 값으로 씁니다.

어디에 저장하나 — 머신 홈의 .env 하나. 세 변수는 머신 홈 디렉터리의 ~/.hermes/.env 파일 한 곳에 둡니다. 프로필마다 따로 두는 것이 아닙니다. 우리가 띄울 대시보드는 머신 전체를 다루는 대시보드(machine dashboard)라, 자격증명도 머신 .env 하나로 모든 직원에 공통 적용됩니다. WSL 터미널에서 아래처럼 한 번에 넣을 수 있습니다.

cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=본인-비밀번호
HERMES_DASHBOARD_BASIC_AUTH_SECRET=위에서-만든-난수-붙여넣기
EOF
chmod 600 ~/.hermes/.env

⚠️ SECRET 값은 한 번 정하면 바꾸지 마세요. 이 값이 고정돼야 대시보드를 재시작해도 로그인 상태가 유지됩니다. 매번 바뀌면 그때마다 다시 로그인해야 합니다.

💡 chmod 600은 이 파일을 본인만 읽고 쓰도록 잠그는 명령입니다. 비밀번호가 든 파일이니 꼭 걸어주세요. 파일 브라우저로 직접 열어 편집하셔도 됩니다. 경로는 헤르메스 홈(~/.hermes) 안의 .env입니다.

이제 대시보드를 띄웁니다. 환경 변수를 저장했으면, WSL 터미널에서 대시보드를 외부 접속이 가능하도록 띄웁니다.

hermes dashboard --no-open --host 0.0.0.0 --port 9119

⚠️ --isolated를 붙이지 않는 것이 핵심입니다. 이렇게 띄우면 대시보드 하나로 모든 프로필(직원)을 다룰 수 있어, 직원마다 서버를 따로 띄울 필요가 없습니다. 대시보드가 뜨면 접속 시 아이디와 비밀번호를 묻고, 위에서 정한 값으로 로그인하면 됩니다.

관문 3 — 토큰 칸이 아니라 Sign in으로 로그인

비밀번호를 켜두면, 데스크톱 앱에서 토큰을 묻던 칸이 Sign in 버튼으로 바뀝니다. 이제 데스크톱 앱으로 돌아와 화면을 보며 차근차근 연결해 보겠습니다.

1단계. 데스크톱 앱에서 Settings → Gateway. 앱 상단의 Open Settings를 누르고, 왼쪽 패널에서 Gateway를 선택합니다.

2단계. Remote gateway 선택. 연결 방식이 두 카드로 나옵니다. 오른쪽 Remote gateway를 클릭해 선택합니다(체크 표시가 뜹니다). 왼쪽 Local gateway는 이 컴퓨터의 백엔드를 쓰는 기본값이라, 따로 띄운 대시보드에 붙으려면 Remote를 골라야 합니다.

3단계. Remote URL 입력. Remote URL 칸에 대시보드 주소를 넣습니다.

• 같은 컴퓨터에서 띄운 대시보드라면 http://localhost:9119
• WSL 안의 대시보드에 붙는 경우라면, 관문 1에서 본 대로 localhost가 아니라 WSL 주소를 넣습니다. 예: http://172.26.x.x:9119

4단계. Save and reconnect → Sign in 클릭. Save and reconnect를 누릅니다. 비밀번호로 보호된 대시보드라면 Authentication 섹션에 Sign in 버튼이 활성화됩니다. 그 버튼을 클릭하세요.

5단계. 아이디·비밀번호로 로그인. Sign in 창이 뜨면, 관문 2에서 ~/.hermes/.env에 넣어 둔 USERNAME과 PASSWORD를 입력하고 SIGN IN을 누릅니다.

6단계. 연결 확인. 로그인에 성공하면 Authentication 섹션이 Signed in(체크)으로 바뀌고 옆에 Sign out 버튼이 보입니다. 이제 앱에 프로필 목록이 나타납니다.

> 💡 프로필 목록이 안 보이면 Save and reconnect를 한 번 더 누르거나, Local gateway와 Remote gateway를 번갈아 눌러 Sign in을 다시 활성화하세요. 직원이 여러 명이면 각 직원으로 처음 넘어갈 때 한 번씩 같은 비밀번호로 로그인하면 됩니다.

💡 이 원리를 쓰면 WSL뿐 아니라, Hostinger 같은 원격 VPS의 헤르메스에도 내 PC의 데스크톱 앱을 붙여 쓸 수 있습니다. 서버 하나, 비밀번호 하나로 회사 전체를 이 앱에서 운영하는 셈입니다.

프로필 레일로 직원 전환하기

연결을 마친 뒤 데스크톱 앱을 종료했다가 다시 켜면, 앱 하단의 프로필 레일(ProfileRail) 영역에 직원들이 단축 버튼으로 쭉 나열됩니다. 각 버튼을 클릭하면 그 직원으로 손쉽게 전환되고, 스킬·도구·MCP·설정까지 그 사람 기준으로 바뀝니다.

> 💡 버튼이 안 보이면 각 직원으로 한 번씩 로그인했는지 확인하세요. 한 번 로그인해 둔 직원은 다음부터 이 레일에서 클릭 한 번으로 오갈 수 있습니다.

3. (다음 단계) 대시보드를 24시간 켜두기

이렇게 띄운 대시보드는 터미널을 닫으면 같이 꺼집니다. 재부팅에도 알아서 다시 뜨게 하려면 systemd(리눅스/WSL)나 launchd(맥)에 등록합니다. 자세한 방법은 대시보드 영구 호스팅 가이드를 참고하세요.

자주 만나는 문제

직원(프로필)들이 안 보입니다.게이트웨이가 Local로 되어 있을 가능성이 큽니다. 윈도우(WSL) 사용자는 Remote gateway로 바꾸고 WSL 주소로 로그인해야 우리 회사가 보입니다. 그래도 안 보이면 Save and Reconnect를 누르세요.

Could not reach로 연결이 안 됩니다.주소를 다시 확인하세요. localhost가 아니라 WSL IP(또는 Tailscale 주소)여야 하고, https가 아니라 http입니다.

대시보드를 열자마자 Refusing to bind 같은 메시지가 뜹니다.0.0.0.0으로 외부에 열 때는 비밀번호(basic auth)가 반드시 필요합니다. 관문 2의 환경 변수 세 개를 ~/.hermes/.env에 넣었는지 확인하세요.

재시작하면 매번 다시 로그인해야 합니다.SECRET 값이 고정되지 않은 경우입니다. openssl rand로 만든 값을 .env에 한 번 넣고 그대로 두세요.

마무리

이제 같은 회사를 터미널이 아니라 손에 잡히는 앱으로 운영할 수 있게 됐습니다. 표면이 터미널이든 웹이든 앱이든, 부리는 것은 결국 같은 코어 하나입니다. 화면을 바꿔 끼는 사람이 아니라, 어디서든 같은 팀을 부리는 오케스트레이터인 셈입니다.