hermes-agent/website/docs/user-guide/messaging/web.md

sidebar_position, title, description

sidebar_position	title	description
8	Web UI	Access Hermes from any browser on your network — phone, tablet, or desktop

Web UI Setup

Access Hermes from any browser on your local network. Open the URL on your phone, tablet, or another computer — no app install, no third-party account needed.

:::info No External Dependencies The Web adapter uses aiohttp, which is already included in the [messaging] extra. No additional packages or external services are required. :::

Overview

Component	Value
Library	aiohttp (HTTP + WebSocket)
Connection	Local network (LAN)
Auth	Token-based (auto-generated or custom)
Features	Markdown, code highlighting, voice messages, images, mobile responsive

---

Quick Start

Option 1: On-Demand via Command

Start the gateway normally, then type from any connected platform (Telegram, Discord, etc.):

/remote-control

The bot replies with the URL and access token. Open the URL on your phone.

You can also specify a custom port and token:

/remote-control 9000 mysecrettoken

Option 2: Auto-Start with Gateway

Add to ~/.hermes/.env:

WEB_UI_ENABLED=true
WEB_UI_PORT=8765          # default: 8765
WEB_UI_TOKEN=mytoken      # auto-generated if empty

Start the gateway:

hermes gateway

The web UI starts automatically alongside your other platforms.

---

Step 1: Configure

Add to ~/.hermes/.env:

# Enable Web UI
WEB_UI_ENABLED=true

# Port to listen on (default: 8765)
WEB_UI_PORT=8765

# Bind address (default: 0.0.0.0 = all interfaces, for LAN access)
# Set to 127.0.0.1 for localhost-only access
WEB_UI_HOST=0.0.0.0

# Access token (leave empty to auto-generate on each startup)
WEB_UI_TOKEN=your-secret-token

Step 2: Start the Gateway

hermes gateway

You'll see output like:

[Web] Web UI: http://192.168.1.106:8765
[Web] Access token: your-secret-token

Step 3: Open in Browser

1. Open the URL shown in the console on any device on the same network
2. Enter the access token
3. Start chatting

---

Features

Markdown & Code Highlighting

Bot responses render full GitHub-flavored Markdown with syntax-highlighted code blocks powered by highlight.js.

Voice Conversation

Click the microphone button to record a voice message. The audio is transcribed via Whisper STT (using OpenAI or Groq as fallback) and sent to the agent. The bot automatically replies with audio playback — voice first, then the text response appears. No extra configuration needed.

STT priority: VOICE_TOOLS_OPENAI_KEY (OpenAI Whisper) > GROQ_API_KEY (Groq Whisper). TTS uses Edge TTS (free, no key) by default, or ElevenLabs/OpenAI if configured in ~/.hermes/config.yaml.

Images & Files

• Images display inline in the chat
• Documents show as download links
• Generated images from the agent appear automatically

Mobile Responsive

The UI adapts to phone screens — full chat experience with touch-friendly input and buttons.

Typing Indicator

Shows an animated indicator while the agent is processing your message.

Auto-Reconnect

If the connection drops (server restart, network change), the client automatically reconnects with exponential backoff.

---

Firewall & Network

macOS Firewall

macOS may block incoming connections by default. If devices on your network can't connect:

1. System Settings > Network > Firewall
2. Either disable the firewall temporarily, or add Python to the allowed apps

Localhost Only

To restrict access to the local machine only:

WEB_UI_HOST=127.0.0.1

Remote Access (Outside LAN)

The Web UI is designed for local network access. For access from outside your network, use a tunnel:

# Using ngrok
ngrok http 8765

# Using Cloudflare Tunnel
cloudflared tunnel --url http://localhost:8765

# Using Tailscale (recommended — encrypted, no port forwarding)
# Install Tailscale on both devices, then access via Tailscale IP

---

Security

• Token authentication — every WebSocket connection must authenticate with the correct token before sending messages
• No data leaves your network — the server runs locally, chat data stays on your machine
• No HTTPS by default — traffic is unencrypted on the LAN. Use a reverse proxy or tunnel for encryption
• File uploads require the auth token in the Authorization header
• Media cleanup — uploaded and generated files are automatically deleted after 24 hours

---

Environment Variables

Variable	Default	Description
WEB_UI_ENABLED	false	Enable the web gateway
WEB_UI_PORT	8765	HTTP server port
WEB_UI_HOST	0.0.0.0	Bind address (0.0.0.0 = LAN, 127.0.0.1 = localhost)
WEB_UI_TOKEN	(auto)	Access token. Auto-generated if empty.

---

Troubleshooting

"Server not found" on phone

• Verify both devices are on the same WiFi network
• Check if macOS firewall is blocking (see Firewall section above)
• Try the IP address shown in console output, not localhost
• If using VPN, the console shows all available IPs — try each one

Port already in use

Change the port in .env:

WEB_UI_PORT=9000

Voice recording not working

• Browser must support MediaRecorder API (Chrome, Firefox, Safari 14.5+)
• HTTPS is required for microphone access on non-localhost origins
• On localhost (127.0.0.1), HTTP works fine for microphone

CDN resources not loading

The UI loads marked.js and highlight.js from CDN. If you're offline or behind a restrictive proxy, markdown rendering and code highlighting won't work but basic chat still functions.