Hermes WebUI 설치 및 사용법 총정리: Hermes Agent를 웹 브라우저와 모바일에서 사용하는 방법

AI Agent · Self-hosted · Web UI

Hermes WebUI 설치 및 사용법 총정리

Hermes WebUI는 Hermes Agent를 터미널이 아닌 웹 브라우저에서 사용할 수 있게 해주는 오픈소스 웹 인터페이스입니다. 이 글에서는 설치 준비부터 실행, Docker 구성, 비밀번호 인증, 원격 접속, 모바일 접속, 환경 변수 설정까지 실무 기준으로 정리합니다.

대상: 개발자 / AI Agent 사용자 난이도: 초급~중급 기준 저장소: nesquena/hermes-webui 기본 포트: 8787

1. Hermes WebUI란?

Hermes WebUI는 Hermes Agent를 웹 브라우저에서 사용할 수 있도록 만든 경량 웹 인터페이스입니다. Hermes Agent는 서버에서 동작하는 자율형 AI 에이전트이며, 터미널이나 메시징 앱을 통해 사용할 수 있습니다. Hermes WebUI는 이 Hermes Agent를 더 편하게 사용할 수 있도록 브라우저 기반 채팅 UI, 세션 관리, 작업 공간 파일 브라우저, 설정 관리 기능을 제공합니다.

공식 저장소 설명에 따르면 Hermes WebUI는 별도의 프론트엔드 빌드 단계나 프레임워크 없이 Python과 Vanilla JavaScript 중심으로 구성되어 있습니다. 즉, 복잡한 Node.js 빌드 환경을 별도로 구성하지 않아도 비교적 간단하게 실행할 수 있다는 장점이 있습니다.

핵심 요약

Hermes WebUI는 Hermes Agent를 브라우저에서 사용하기 위한 Self-hosted Web UI입니다. 로컬 PC, 서버, VPS, NAS 등에 설치하여 개인용 AI 에이전트 인터페이스로 활용할 수 있습니다.

2. Hermes WebUI의 주요 특징

브라우저 기반 AI Agent 채팅

Hermes WebUI는 Hermes Agent와 대화할 수 있는 웹 채팅 화면을 제공합니다. 응답 스트리밍, 이전 메시지 수정, 응답 재생성, 실행 중인 작업 중지 등 일반적인 AI 채팅 UI에서 기대하는 기능을 제공합니다.

세션 관리

대화 세션을 생성, 검색, 이름 변경, 복제, 삭제할 수 있습니다. 프로젝트나 태그 단위로 세션을 정리할 수 있어 여러 작업을 동시에 진행하는 사용자에게 유용합니다.

워크스페이스 파일 브라우저

오른쪽 패널에서 작업 공간의 파일을 탐색하고, 코드·Markdown·이미지 등을 미리 볼 수 있습니다. 일부 파일 편집 기능도 제공하므로 AI Agent를 이용한 코드 작업이나 문서 작업에 적합합니다.

모델 및 프로필 관리

OpenAI, Anthropic, Google, DeepSeek, OpenRouter 등 Hermes Agent가 지원하는 여러 제공자를 사용할 수 있으며, WebUI 안에서 프로필을 만들고 전환할 수 있습니다.

보안 기능

기본적으로 로컬 접속에 맞춰져 있으며, 필요할 경우 HERMES_WEBUI_PASSWORD 환경 변수를 사용해 비밀번호 인증을 설정할 수 있습니다. 원격 서버에서 사용할 때는 반드시 비밀번호 인증과 SSH 터널 또는 Tailscale 같은 사설 네트워크 구성을 함께 사용하는 것이 좋습니다.

3. 설치 전 준비사항

Hermes WebUI를 사용하기 전에 다음 환경을 준비하는 것이 좋습니다.

항목	설명
운영체제	Linux, macOS, WSL2 권장. 공식 문서 기준 Native Windows Bootstrap은 아직 지원되지 않습니다.
Python	Python 3 환경이 필요합니다.
Git	GitHub 저장소를 내려받기 위해 필요합니다.
Hermes Agent	Bootstrap 실행 시 Hermes Agent가 없으면 설치를 시도합니다.
Docker	컨테이너 방식으로 실행하려면 Docker 또는 Docker Compose가 필요합니다.

Windows 사용자는?

Windows에서 바로 실행하기보다는 WSL2 환경을 사용하는 것이 안전합니다. 공식 문서에서도 Native Windows Bootstrap은 아직 지원되지 않는다고 안내하고 있습니다.

4. 가장 쉬운 설치 방법: Bootstrap 실행

가장 간단한 방법은 GitHub 저장소를 복제한 뒤 bootstrap.py를 실행하는 것입니다.

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

Bootstrap 스크립트는 Hermes Agent를 감지하고, 없을 경우 공식 설치 스크립트를 통해 설치를 시도합니다. 이후 Python 환경을 준비하고 WebUI 서버를 실행한 뒤, 브라우저에서 첫 실행 온보딩 화면으로 이동합니다.

기존 방식으로 start.sh 실행하기

Bootstrap 대신 기존 Shell Launcher를 사용할 수도 있습니다.

./start.sh

실행 후 기본적으로 다음 주소에서 WebUI를 열 수 있습니다.

http://localhost:8787

추천 방식

처음 사용하는 경우에는 python3 bootstrap.py를 권장합니다. Hermes Agent 감지, 의존성 준비, 서버 실행, 첫 설정 안내까지 한 번에 처리되기 때문입니다.

5. Docker로 실행하는 방법

Docker를 사용하면 로컬 Python 환경을 직접 구성하지 않고 Hermes WebUI를 실행할 수 있습니다. 공식 이미지는 GitHub Container Registry에 배포되어 있습니다.

공식 이미지 다운로드

docker pull ghcr.io/nesquena/hermes-webui:latest

Docker Run 실행 예시

docker run -d \
  -e WANTED_UID=$(id -u) \
  -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp \
  -v ~/workspace:/workspace \
  -p 8787:8787 \
  ghcr.io/nesquena/hermes-webui:latest

실행 후 브라우저에서 다음 주소로 접속합니다.

http://localhost:8787

권한 설정이 중요한 이유

Docker 컨테이너가 호스트의 ~/.hermes 디렉터리와 워크스페이스를 마운트하기 때문에 UID/GID가 맞지 않으면 파일 읽기·쓰기 권한 문제가 발생할 수 있습니다. 그래서 WANTED_UID, WANTED_GID 값을 현재 사용자 ID와 그룹 ID로 맞추는 것이 좋습니다.

6. Docker Compose로 실행하는 방법

운영 환경이나 서버 환경에서는 Docker Compose 방식이 더 관리하기 쉽습니다.

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
docker compose up -d

공식 docker-compose.yml은 기본적으로 127.0.0.1:8787:8787 형태로 로컬 호스트에서만 접근되도록 구성되어 있습니다. 외부 네트워크에서 직접 접근시키려면 포트 바인딩을 8787:8787로 변경할 수 있지만, 이 경우 반드시 비밀번호 인증을 함께 설정해야 합니다.

.env 파일 예시

UID=1000
GID=1000
HERMES_HOME=/home/your-user/.hermes
HERMES_WORKSPACE=/home/your-user/workspace

macOS에서는 UID가 501부터 시작하는 경우가 많으므로 다음 명령어로 실제 값을 확인한 뒤 설정하는 것이 좋습니다.

id -u
id -g

Hermes Agent + Dashboard + WebUI 함께 실행하기

Hermes Agent, Hermes Dashboard, Hermes WebUI를 함께 실행하려면 3개 컨테이너 구성을 사용할 수 있습니다.

docker compose -f docker-compose.three-container.yml up -d

이 구성에서는 Hermes Agent는 8642, Hermes Dashboard는 9119, Hermes WebUI는 8787 포트를 사용합니다.

7. 비밀번호 인증 설정

Hermes WebUI는 로컬 사용을 쉽게 하기 위해 기본적으로 비밀번호 인증이 꺼져 있습니다. 하지만 원격 서버, NAS, VPS, 사내 서버에서 사용할 경우 반드시 비밀번호를 설정해야 합니다.

start.sh 실행 시 비밀번호 설정

HERMES_WEBUI_PASSWORD=your-secure-password ./start.sh

Docker 실행 시 비밀번호 설정

docker run -d \
  -e WANTED_UID=$(id -u) \
  -e WANTED_GID=$(id -g) \
  -v ~/.hermes:/home/hermeswebui/.hermes \
  -e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui-mvp \
  -v ~/workspace:/workspace \
  -p 8787:8787 \
  -e HERMES_WEBUI_PASSWORD=your-secure-password \
  ghcr.io/nesquena/hermes-webui:latest

주의

HERMES_WEBUI_HOST=0.0.0.0 또는 8787:8787처럼 외부 네트워크에서 접근 가능하게 설정할 경우, 비밀번호 없이 공개하면 매우 위험합니다. 가능하면 SSH 터널, VPN, Tailscale과 함께 사용하세요.

8. 원격 서버에서 접속하는 방법

Hermes WebUI는 기본적으로 127.0.0.1에 바인딩되어 로컬에서만 접근됩니다. VPS나 원격 서버에서 실행 중이라면 SSH 터널을 사용하는 방식이 안전합니다.

SSH 터널 명령어

ssh -N -L 8787:127.0.0.1:8787 user@your.server.com

위 명령을 실행한 뒤 내 컴퓨터 브라우저에서 다음 주소로 접속합니다.

http://localhost:8787

이 방식은 서버의 8787 포트를 인터넷에 직접 노출하지 않고, SSH 연결을 통해 로컬 브라우저에서 접근할 수 있게 해줍니다.

9. 모바일에서 접속하는 방법

휴대폰에서 Hermes WebUI를 사용하려면 Tailscale 같은 사설 네트워크 도구를 사용하는 방법이 좋습니다. Tailscale을 서버와 휴대폰에 설치하면, 포트포워딩 없이 같은 사설 네트워크 안에서 접속할 수 있습니다.

Tailscale 기반 접속 흐름

서버와 휴대폰에 Tailscale을 설치합니다.
서버에서 Hermes WebUI를 모든 인터페이스에 바인딩하고 비밀번호 인증을 켭니다.
휴대폰 브라우저에서 서버의 Tailscale IP와 포트 8787로 접속합니다.

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secure-password ./start.sh

http://SERVER_TAILSCALE_IP:8787

모바일 사용 팁

Hermes WebUI는 반응형 UI를 지원하므로 스마트폰 브라우저에서도 사용할 수 있습니다. 자주 사용한다면 모바일 브라우저에서 홈 화면에 추가해 앱처럼 사용하는 것도 좋습니다.

10. 주요 환경 변수 정리

Hermes WebUI는 대부분 자동 감지를 지원하지만, 환경에 따라 직접 경로와 포트를 지정해야 할 수 있습니다.

환경 변수	기본값 / 설명
`HERMES_WEBUI_AGENT_DIR`	Hermes Agent 저장소 경로를 직접 지정합니다.
`HERMES_WEBUI_PYTHON`	사용할 Python 실행 파일을 지정합니다.
`HERMES_WEBUI_HOST`	기본값은 `127.0.0.1`입니다. 외부 접속이 필요하면 `0.0.0.0`을 사용할 수 있습니다.
`HERMES_WEBUI_PORT`	기본 포트는 `8787`입니다.
`HERMES_WEBUI_STATE_DIR`	세션, 워크스페이스, 설정 등 WebUI 상태 저장 경로입니다.
`HERMES_WEBUI_DEFAULT_WORKSPACE`	첫 실행 시 보여줄 기본 작업 공간 경로입니다.
`HERMES_WEBUI_PASSWORD`	설정하면 로그인 비밀번호 인증이 활성화됩니다.
`HERMES_HOME`	Hermes 전체 상태 디렉터리입니다. 일반적으로 `~/.hermes`를 사용합니다.
`HERMES_CONFIG_PATH`	Hermes 설정 파일 경로입니다. 일반적으로 `~/.hermes/config.yaml`입니다.

포트를 9000으로 바꿔 실행하는 예시

HERMES_WEBUI_PORT=9000 ./start.sh

Agent 경로를 직접 지정하는 예시

HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent ./start.sh

11. 자주 발생하는 문제와 해결 방법

문제 1. 브라우저에서 접속이 안 되는 경우

먼저 서버가 정상적으로 실행 중인지 확인합니다.

curl http://127.0.0.1:8787/health

포트를 변경했다면 8787 대신 변경한 포트로 확인해야 합니다.

문제 2. Docker에서 PermissionError가 발생하는 경우

~/.hermes 디렉터리 소유권이 현재 사용자와 맞지 않을 수 있습니다.

sudo chown -R $(id -u):$(id -g) ~/.hermes

Docker Compose 사용 시에는 .env 파일에 UID/GID를 명확히 지정하세요.

echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

문제 3. 원격 서버에서 외부 접속이 안 되는 경우

기본 설정은 127.0.0.1 로컬 바인딩입니다. 외부 접속이 필요하다면 다음 중 하나를 선택하세요.

SSH 터널 사용: 가장 안전하고 추천되는 방식
Tailscale 사용: 모바일이나 여러 기기에서 접근하기 좋음
HERMES_WEBUI_HOST=0.0.0.0 설정: 반드시 비밀번호 인증과 함께 사용

문제 4. Native Windows에서 실행이 어려운 경우

공식 문서 기준 Native Windows Bootstrap은 아직 지원되지 않습니다. Windows 사용자는 WSL2 환경에서 설치하는 것을 권장합니다.

12. 마무리

Hermes WebUI는 Hermes Agent를 더 편하게 사용하고 싶은 사용자에게 적합한 웹 인터페이스입니다. 터미널 중심의 사용 방식이 부담스럽거나, 모바일·원격 서버·브라우저 기반으로 AI Agent를 관리하고 싶다면 Hermes WebUI를 설치해볼 만합니다.

처음 설치한다면 python3 bootstrap.py 방식으로 시작하는 것이 가장 쉽고, 서버에서 장기적으로 운영하려면 Docker Compose 방식이 관리하기 좋습니다. 외부 접속이 필요한 경우에는 반드시 HERMES_WEBUI_PASSWORD를 설정하고, SSH 터널 또는 Tailscale 같은 안전한 접속 방식을 함께 사용하는 것을 권장합니다.

Hermes WebUI Hermes Agent AI Agent Self-hosted AI Docker SSH Tunnel Tailscale Web UI

13. 출처

'AI' 카테고리의 다른 글

Hermes Agent 디스코드 봇 연결 방법 완벽 가이드: 설치부터 Bot Token, Gateway 실행, 보안 설정까지 (0)	2026.05.02
Warp 터미널 사용법 완벽 가이드: AI Agent Mode, 설치, GitHub 오픈소스 빌드까지 (1)	2026.04.30
UI-TARS란? ByteDance가 공개한 GUI 자동화 AI 에이전트 모델 완벽 분석 (1)	2026.04.25
AI 오케스트레이션 완벽 가이드: 멀티 에이전트, 워크플로우, 도구 라우팅, LangGraph·CrewAI·OpenAI Agents SDK 비교분석 (8)	2026.04.25
클로드 디자인 설치 및 사용법 완벽 가이드: Claude Design으로 UI·프로토타입·프레젠테이션 만드는 방법 (0)	2026.04.21

민서의 개발 블로그

Hermes WebUI 설치 및 사용법 총정리: Hermes Agent를 웹 브라우저와 모바일에서 사용하는 방법

Hermes WebUI 설치 및 사용법 총정리

1. Hermes WebUI란?

2. Hermes WebUI의 주요 특징

브라우저 기반 AI Agent 채팅

세션 관리

워크스페이스 파일 브라우저

모델 및 프로필 관리

보안 기능

3. 설치 전 준비사항

4. 가장 쉬운 설치 방법: Bootstrap 실행

기존 방식으로 start.sh 실행하기

5. Docker로 실행하는 방법

공식 이미지 다운로드

Docker Run 실행 예시

6. Docker Compose로 실행하는 방법

.env 파일 예시

Hermes Agent + Dashboard + WebUI 함께 실행하기

7. 비밀번호 인증 설정

start.sh 실행 시 비밀번호 설정

Docker 실행 시 비밀번호 설정

8. 원격 서버에서 접속하는 방법

SSH 터널 명령어

9. 모바일에서 접속하는 방법

Tailscale 기반 접속 흐름

10. 주요 환경 변수 정리

포트를 9000으로 바꿔 실행하는 예시

Agent 경로를 직접 지정하는 예시

11. 자주 발생하는 문제와 해결 방법

문제 1. 브라우저에서 접속이 안 되는 경우

문제 2. Docker에서 PermissionError가 발생하는 경우

문제 3. 원격 서버에서 외부 접속이 안 되는 경우

문제 4. Native Windows에서 실행이 어려운 경우

12. 마무리

13. 출처

'AI' 카테고리의 다른 글

티스토리툴바

Hermes WebUI 설치 및 사용법 총정리: Hermes Agent를 웹 브라우저와 모바일에서 사용하는 방법

Hermes WebUI 설치 및 사용법 총정리

1. Hermes WebUI란?

2. Hermes WebUI의 주요 특징

브라우저 기반 AI Agent 채팅

세션 관리

워크스페이스 파일 브라우저

모델 및 프로필 관리

보안 기능

3. 설치 전 준비사항

4. 가장 쉬운 설치 방법: Bootstrap 실행

기존 방식으로 start.sh 실행하기

5. Docker로 실행하는 방법

공식 이미지 다운로드

Docker Run 실행 예시

6. Docker Compose로 실행하는 방법

.env 파일 예시

Hermes Agent + Dashboard + WebUI 함께 실행하기

7. 비밀번호 인증 설정

start.sh 실행 시 비밀번호 설정

Docker 실행 시 비밀번호 설정

8. 원격 서버에서 접속하는 방법

SSH 터널 명령어

9. 모바일에서 접속하는 방법

Tailscale 기반 접속 흐름

10. 주요 환경 변수 정리

포트를 9000으로 바꿔 실행하는 예시

Agent 경로를 직접 지정하는 예시

11. 자주 발생하는 문제와 해결 방법

문제 1. 브라우저에서 접속이 안 되는 경우

문제 2. Docker에서 PermissionError가 발생하는 경우

문제 3. 원격 서버에서 외부 접속이 안 되는 경우

문제 4. Native Windows에서 실행이 어려운 경우

12. 마무리

13. 출처

'AI' 카테고리의 다른 글

'AI' Related Articles

티스토리툴바