Hermes Agent 웹 대시보드: 로컬 접속, 프로필 및 장애 진단 가이드

그래픽 웹 인터페이스인 Hermes Agent Web Dashboard는 구성 파일을 직접 수정하지 않고 브라우저에서 에이전트 설치 환경을 직접 관리할 수 있도록 지원합니다. 이 대시보드를 사용하면 시스템 환경 변수를 수동으로 편집하지 않고도 API 접근 키를 관리하고, 활성 프로필을 전환하며, 이전 세션 기록을 점검하고 내장 터미널을 실행할 수 있습니다.

기본 실행 및 시스템 의존성

기본적으로 웹 대시보드는 루프백(loopback) 인터페이스에 바인딩됩니다:

hermes dashboard

이 명령은 로컬 HTTP 서버를 시작하고 기본 브라우저에서 http://127.0.0.1:9119를 엽니다. 해당 포트가 이미 다른 로컬 서비스에서 사용 중인 경우 --port 플래그로 포트를 재지정할 수 있습니다:

hermes dashboard --port 9120 --no-open

--no-open 플래그는 새 브라우저 탭이 자동으로 열리는 것을 방지하므로, 백그라운드 프로세스 실행이나 자동화 스크립트에 적합합니다.

기본 hermes-agent 패키지에는 웹 스택이 기본적으로 포함되어 있지 않습니다. Linux, macOS 및 WSL2 환경에서는 에이전트의 가상 환경에 필요한 선택적 컴포넌트를 설치해야 합니다:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"

web 엑스트라 패키지는 FastAPI와 Uvicorn을 설치하며, pty는 POSIX 시스템을 위한 ptyprocess를 추가합니다. 대시보드의 정적 프론트엔드를 빌드하려면 Node.js가 설치되어 있어야 합니다(npm이 감지되면 첫 실행 시 프론트엔드가 자동으로 빌드됩니다).

플랫폼 경계: 네이티브 Windows와 WSL2

Windows (Native) 가이드에 따르면, 네이티브 Windows 환경에서는 설정(Config), 지표(Metrics), 작업(Tasks), 세션 데이터베이스 뷰를 정상적으로 지원합니다. 하지만 내장 터미널 탭인 /chat은 POSIX PTY 의사 터미널(pseudo-terminal)에 의존합니다. 네이티브 Windows 환경에서는 이 인터페이스를 지원하지 않으므로, 브라우저 내에서 완전한 대화형 터미널 세션을 이용하려면 에이전트를 WSL2 내부에서 실행해야 합니다.

또한 프로세스를 명확히 분리하여 이해하는 것이 중요합니다. 웹 대시보드와 메시징 게이트웨이(Telegram, Discord 및 기타 플랫폼 연동)는 서로 독립적인 데몬으로 동작합니다. 웹 인터페이스를 실행한다고 해서 플랫폼 메시징 게이트웨이가 자동으로 활성화되거나 실행되는 것은 아닙니다.

프로필 관리 및 모델 구성

대시보드는 머신(시스템) 전체 수준에서 동작하며, 생성된 모든 프로필을 중앙에서 관리합니다. 사이드바의 프로필 전환기를 사용하면 URL 쿼리 파라미터 ?profile=<name>을 통해 작업 컨텍스트가 전환됩니다.

1. Config 및 API Keys 섹션: Config 페이지에서는 config.yaml의 매개변수를 편집하며, 변경 사항은 Save 버튼을 클릭하여 적용합니다. 반면 API Keys 페이지는 ~/.hermes/.env 파일의 환경 변수를 관리합니다. 키는 전체 필드에 대한 일괄 저장 버튼이나 일괄 유효성 검사 없이 각 변수별로 개별 설정 및 제거됩니다.
2. 프로바이더와 모델의 일치성: 선택한 모델과 인증 자격 증명은 반드시 동일한 단일 프로바이더와 엄격하게 일치해야 합니다. 서드파티 OpenAI 호환 서비스를 연동할 때는 업스트림 제공자의 공식 사양을 확인해야 합니다. 예를 들어 최신 파라미터, 모델 ID 및 연결 설정은 BetterToken 가이드에 설명되어 있습니다. 서드파티 프로바이더는 모델에 대한 독립적인 API 접근만을 제공하며, Hermes 대시보드를 직접 호스팅하거나 네트워크 터널을 관리하지 않습니다.
3. Sessions를 통한 정상 동작 확인: 수동으로 헬스 체크를 수행할 때는 짧은 읽기 전용 프롬프트를 전송하십시오. 테스트 요청 역시 프로바이더에 의해 요금이 청구될 수 있다는 점에 유의해야 합니다. 성공적인 추론(inference)의 기준은 인터페이스에 실질적인 응답이 반환되고 세션 메타데이터 또는 프로바이더 콘솔에서 토큰 소비가 기록되는 것입니다. 단순히 Sessions 탭 목록에 새 항목이 생성되는 것만으로는 레코드 생성을 의미할 뿐, 모델이 성공적으로 응답했음을 보증하지 않습니다.

안전한 원격 접속

기본 설정 상태에서 웹 서버는 오직 127.0.0.1에서만 요청을 수신합니다. 외부 인터페이스에 바인딩할 경우(--host 0.0.0.0) 인증 게이트(auth gate)가 자동으로 활성화됩니다. 인증 프로바이더가 구성되어 있지 않으면 에이전트는 오류를 발생시키며 즉시 종료(fail-closed)됩니다. 레거시 플래그인 --insecure는 더 이상 인증 검사를 우회하지 않습니다. 공개 또는 외부 네트워크 바인딩에는 Hermes Agent 공식 문서에 따라 필수적인 인증 구성이 요구됩니다.

외부 포트를 외부에 직접 개방하지 않고 원격 서버에 안전하게 연결하는 권장 방법은 SSH 터널을 통한 로컬 포트 포워딩입니다 (user@your-server를 원격 서버의 사용자명과 서버 주소로 변경):

ssh -N -L 9119:127.0.0.1:9119 user@your-server

로컬 작업 컴퓨터의 9119 포트가 이미 다른 프로세스에 의해 사용 중이라면 대체 로컬 포트를 지정하십시오:

ssh -N -L 9120:127.0.0.1:9119 user@your-server

이 방식을 적용하면 원격 호스트의 Hermes 서버는 로컬 127.0.0.1 루프백 인터페이스에서만 안전하게 실행을 유지하고, 모든 트래픽은 SSH 터널을 통해 암호화되며, 로컬 작업 컴퓨터의 브라우저에서 http://127.0.0.1:9119(또는 대체 포트 사용 시 http://127.0.0.1:9120)로 대시보드에 접근할 수 있습니다.

단계별 장애 진단

오류가 발생했을 때는 전체 스택을 한꺼번에 점검하지 말고, 문제가 발생한 계층을 개별적으로 격리하여 분석하는 것이 중요합니다.

+----------------------------------------------------------------+
| 1. HTTP-транспорт      | 127.0.0.1:9119 /api/status            |
+------------------------+---------------------------------------+
| 2. Окружение и PTY     | Node.js / POSIX ptyprocess (WSL2)     |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы     | /api/pty (Chat) / /api/ws (Desktop)   |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт  |
+----------------------------------------------------------------+

위 의사결정 트리 다이어그램의 각 계층은 다음 진단 영역을 나타냅니다:

• 1단계 (HTTP 전송 계층): 127.0.0.1:9119 /api/status
• 2단계 (환경 및 PTY 계층): Node.js / POSIX ptyprocess (WSL2)
• 3단계 (소켓 및 통신 채널): /api/pty (Chat) / /api/ws (Desktop)
• 4단계 (추론 프로바이더 계층): API 키, 쿼터(사용 한도) 및 네트워크 엔드포인트

1. 네트워크 계층 (HTTP): GET /api/status에 대한 성공적인 응답은 Uvicorn 프로세스가 실행 중이며 HTTP 요청을 처리하고 있음을 나타낼 뿐입니다. 이 엔드포인트는 인증을 거치지 않으므로 권한 부여가 통과되었거나 대화형 채팅 인터페이스가 준비되었음을 보장하지는 않습니다.
2. PTY 및 인터페이스 계층: Connection closed 오류는 여러 가지 원인으로 인해 발생할 수 있습니다. 네이티브 Windows 환경에서는 POSIX PTY 미지원이 주요 진단 원인 중 하나이며, 이 경우 실행 환경을 WSL2로 전환해야 합니다. 다른 운영체제 환경에서는 이 증상이 단순 PTY 문제에 국한되지 않으므로 시스템 로그와 소켓 연결 상태를 함께 점검해야 합니다. 스타일 빌드 오류나 흰색 화면(blank screen) 문제가 발생하면 Node.js 버전을 확인하고 프론트엔드 의존성을 다시 빌드하십시오.
3. 소켓 채널 및 인증: 브라우저의 내장 터미널은 /api/pty를 사용하고, 원격 Desktop 클라이언트는 /api/ws를 통해 연결됩니다. 클라이언트에서 백엔드 접속 가능을 보고하지만 세션이 응답하지 않는 경우 해당 채널의 연결을 확인하십시오. 세션 티켓의 누락이나 만료, 또는 바인딩 주소와 Host 헤더가 일치하지 않아 DNS-rebinding 방지 메커니즘에 의해 차단되는 경우가 주된 실패 원인입니다.
4. 모델 프로바이더 계층: 활성 터미널에서 프롬프트를 전송한 후 발생하는 지연이나 오류 메시지는 대부분 API 계층(.env 파일 내 API 키 유효성, 프로바이더 엔드포인트 도달 가능성, 쿼터 및 잔액 초과 등)에서 비롯됩니다. 다만 프로바이더 수준의 오류가 발생했다고 해서 대시보드 서버 자체가 완벽하게 정상 상태라고 단정할 수는 없으며, 런타임 상태와 세션 라이프사이클을 함께 점검해야 할 수도 있습니다.