Hermes 에이전트: 헤드리스 서버 및 원격 데스크톱 설정
원격 데스크톱 액세스를 지원하는 Headless Hermes 서버
데스크톱 클라이언트에서 다른 머신의 헤드리스 서버에 Hermes 에이전트를 실행하고 연결하려면 두 개의 서버 프로세스와 하나의 클라이언트 연결이 필요합니다.
이 아키텍처는 Hermes 백엔드를 두 개의 서버 측 프로세스와 하나의 클라이언트 측 인터페이스로 분리합니다. hermes serve 백엔드는 API 및 대시보드 연결을 처리하고, hermes gateway run 프로세스는 메시징 채널을 독립적으로 관리합니다. 데스크톱 클라이언트는 게이트웨이가 아닌 serve 백엔드에 연결됩니다.
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["DESKTOP PC"] desktop["hermes desktop
(WebSocket connection)"] end desktop <--->|WebSocket| serve gateway -.->|Shares ~/.hermes/| serve
서버에는 두 개의 프로세스, 클라이언트에는 하나의 애플리케이션이 있습니다. 두 서버 프로세스는 동일한 ~/.hermes/ 구성, 스킬, 메모리 및 세션을 공유합니다. 크론 작업은 게이트웨이가 실행되는 서버에서 실행됩니다.
설치, 프로바이더 설정 및 초기 구성은 Hermes AI 어시스턴트 — 설치, 설정, 워크플로우 및 문제 해결 가이드에서 시작하세요.
헤드리스 서버 설정
1. 인증 구성
신뢰할 수 있는 LAN에서는 기본 인증(Basic auth)으로 충분한 보호를 제공합니다. 자격 증명을 환경 파일에 추가하세요:
cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env
.env 파일은 ~/.hermes/ 아래의 config.yaml과 함께 존재합니다. Hermes는 CLI 오버라이드를 먼저, 그 다음 config.yaml, 그 다음 .env, 마지막으로 빌트인 기본값의 순서로 구성을 해석합니다. 시크릿은 .env에 보관해야 합니다.
2. 백엔드 시작
모든 인터페이스에서 serve 백엔드를 실행합니다:
hermes serve --host 0.0.0.0 --port 9119
백엔드는 포트 9119에서 대기하며 데스크톱 클라이언트로부터의 WebSocket 연결을 받습니다. 다음 상태 확인으로 실행 중인지 확인하세요:
curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# 예상 결과: true "basic"
3. systemd 서비스로 실행
리부팅 후에도 지속되는 서버를 위해 사용자 레벨 systemd 서비스를 설치합니다. /etc/systemd/user/hermes-serve.service에 유닛 파일을 생성하세요:
[Unit]
Description=Hermes Agent Serve Backend
[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure
[Install]
WantedBy=default.target
데몬을 리로드하고 서비스를 활성화한 후 시작합니다:
systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve
서비스 상태를 확인합니다:
systemctl --user status hermes-serve
4. 게이트웨이 시작
게이트웨이는 Telegram, Discord, Slack 등 메시징 채널을 처리하는 별도의 프로세스입니다. 독립적으로 시작합니다:
hermes gateway run
게이트웨이와 serve 백엔드는 두 개의 별도 프로세스입니다. 게이트웨이는 세션을 관리하고 크론 작업을 실행하며 메시지를 라우팅합니다. serve 백엔드는 데스크톱 및 웹 대시보드 연결을 위한 API 인터페이스를 제공합니다. 이들은 동일한 홈 디렉토리를 공유하지만 독립적으로 실행됩니다.
게이트웨이 명령 및 하위 명령의 전체 목록은 Hermes Agent CLI 치트시트를 참조하세요. 주요 인터페이스가 모바일 메시징인 경우, 동일한 게이트웨이 프로세스 위에서 음성 우선 워크플로우를 위해 이 설정을 전화기로 Hermes 음성 제어와 결합하세요.
5. 백엔드 확인
백엔드가 응답하고 인증이 활성화되었는지 확인합니다:
curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
예상 출력:
true
"basic"
인증이 활성화되지 않은 경우 응답에서 auth_required가 false로 표시됩니다. .env 파일에 올바른 변수가 포함되어 있는지 확인하고 구성 변경 후 서비스가 재시작되었는지 확인하세요.
데스크톱 클라이언트에서 연결
옵션 A: Hermes 데스크톱 앱
공식 사이트에서 Hermes Desktop을 설치합니다. 앱을 실행하여 설정 → 게이트웨이 → 원격 게이트웨이로 이동하고 서버 주소를 입력합니다:
http://<server-ip>:9119
서버에서 구성한 사용자 이름과 비밀번호로 로그인합니다.
또는 환경 변수를 통해 원격 URL을 설정할 수 있습니다:
HERMES_DESKTOP_REMOTE_URL=http://<server-ip>:9119 hermes desktop
옵션 B: 웹 대시보드
브라우저에서 http://<server-ip>:9119를 열고 기본 인증 자격 증명으로 로그인합니다. 웹 대시보드는 데스크톱 설치가 필요 없이 Hermes 백엔드에 대한 브라우저 기반 인터페이스를 제공합니다.
옵션 C: CLI
데스크톱 PC의 터미널에서 데스크톱 앱 설정 또는 HERMES_DESKTOP_REMOTE_URL 환경 변수를 통해 원격 URL을 구성합니다. CLI 인터페이스는 데스크톱 앱과 동일한 WebSocket 채널을 통해 연결됩니다.
네트워크 및 보안 고려 사항
| 시나리오 | 권장 사항 |
|---|---|
| 신뢰할 수 있는 LAN | --host 0.0.0.0 + 기본 인증 |
| 인터넷에 노출됨 | Tailscale 사용 (--host <tailscale-ip>) 또는 OAuth 프로바이더 |
| 방화벽 | 서버에서 포트 9119 TCP 개방 |
신뢰할 수 있는 로컬 네트워크에서는 0.0.0.0에 대한 기본 인증이 적절합니다. 서버가 인터넷에 노출된 경우, 0.0.0.0 대신 Tailscale IP에 바인딩하기 위해 Tailscale을 사용하거나 더 강력한 인증을 위해 OAuth 프로바이더를 구성하세요. 백엔드가 외부 연결을 받아야 할 때는 서버 방화벽에서 포트 9119 TCP를 항상 개방해야 합니다.
중요한 프로세스 구분
두 서버 프로세스 간의 분리를 이해하면 일반적인 구성 오류를 방지할 수 있습니다:
hermes serve— 데스크톱 앱과 웹 대시보드가 연결되는 백엔드입니다. API 인터페이스 및 WebSocket 연결을 처리합니다.hermes gateway run— Telegram, Discord, Slack 및 기타 메시징 채널을 처리하는 프로세스입니다. 세션을 관리하고 크론 작업을 실행하며 메시지를 라우팅합니다.- 이들은 서버의 두 개의 별도 프로세스입니다.
~/.hermes/구성, 스킬, 메모리 및 세션을 공유하지만 독립적으로 실행됩니다. - 크론 작업은 게이트웨이가 실행되는 서버에서 실행됩니다.
- 프로필, 스킬 및 메모리는 서버 측에서 구성됩니다. 클라이언트는 이미 구성된 백엔드에 연결합니다.
프로필 우선 구성 및 다양한 프로덕션 역할에 맞게 조정된 스킬에 대해 Hermes AI 어시스턴트 스킬 — 실제 프로덕션 설정을 참조하세요.
문제 해결
데스크톱이 서버에 연결되지 않음
- 백엔드 실행 확인:
systemctl --user status hermes-serve - 포트 개방 확인:
ss -tlnp | grep 9119 - 서버에서 테스트:
curl -s http://localhost:9119/api/status - 클라이언트 머신에서 테스트:
curl -s http://<server-ip>:9119/api/status - 클라이언트 테스트 실패 시 방화벽 규칙 확인:
sudo ufw status또는sudo iptables -L
인증 실패
.env파일 권한 확인:ls -la ~/.hermes/.env(권한은600이어야 함)- 시크릿 생성 확인:
grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env - 구성 변경 후 서비스 재시작:
systemctl --user restart hermes-serve
게이트웨이가 메시지에 응답하지 않음
게이트웨이는 백엔드와 별도의 프로세스입니다. 데스크톱은 연결되지만 메시징 플랫폼이 작동하지 않는 경우:
- 게이트웨이 상태 확인:
hermes gateway status - 중지된 경우 게이트웨이 시작:
hermes gateway start - 로그 검토:
hermes logs gateway -f
참고 자료
- Hermes Agent Desktop App Documentation
- Hermes Agent Configuration Guide
- Hermes Agent Messaging Gateway
- Hermes AI Assistant — Install, Setup, Workflow, and Troubleshooting
- Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts
- Hermes AI Assistant Skills for Real Production Setups
이 기사는 AI Systems 클러스터의 일부이며, 셀프 호스팅 어시스턴트, 검색 아키텍처, 로컬 LLM 인프라 및 관찰 가능성(observability)을 다룹니다.
