Timmy_Foundation/hermes-agent
15
0
Fork 0
Code Issues 247 Pull Requests 14 Actions 1 Packages Projects Releases Wiki Activity

docs: add Web UI setup guide and update gateway docs

Browse Source 
- New web.md with full setup, features, security, and troubleshooting
- Update index.md: architecture diagram, platform table, commands, links
This commit is contained in:
0xbyt4
2026-03-11 19:24:40 +03:00
parent 536be3e0f6
commit db51cfa60e
2 changed files with 236 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
website/docs/user-guide/messaging/index.md
View File

@@ -1,12 +1,12 @@
---
sidebar_position: 1
title: "Messaging Gateway"
description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant — architecture and setup overview"
description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or your browser — architecture and setup overview"
---
# Messaging Gateway
Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home Assistant. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
## Architecture
@@ -15,24 +15,24 @@ Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, Email, or Home
│ Hermes Gateway │
├───────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌────┐│
│ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ │Signal │ │ Email │ │ HA ││
│ │ Adapter │ │ Adapter │ │ Adapter │ │Adapter│ │Adapter│ │Adapter│ │Adpt││
│ └────┬─────┘ └────┬────┘ └────┬─────┘ └──┬────┘ └──┬────┘ └──┬────┘ └─┬──┘│
│ │ │ │ │ │ │ │ │
│ └─────────────┴───────────┴───────────┴─────────┴─────────┴────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Session Store │ │
│ │ (per-chat) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ AIAgent │ │
│ │ (run_agent) │ │
│ └─────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────┘
│ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌────┐ ┌─────┐│
│ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ │Signal │ │ Email │ │ HA │ │ Web ││
│ │ Adapter │ │ Adapter │ │ Adapter │ │Adapter│ │Adapter│ │Adapter│ │Adpt│ │Adpt ││
│ └────┬─────┘ └────┬────┘ └────┬─────┘ └──┬────┘ └──┬────┘ └──┬────┘ └─┬──┘ └──┬──┘│
│ │ │ │ │ │ │ │ │ │
│ └─────────────┴───────────┴───────────┴─────────┴─────────┴────────┴───────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Session Store │ │
│ │ (per-chat) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ AIAgent │ │
│ │ (run_agent) │ │
│ └─────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────┘
```
Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs.
@@ -81,6 +81,7 @@ hermes gateway status # Check service status
| `/background <prompt>` | Run a prompt in a separate background session |
| `/reload-mcp` | Reload MCP servers from config |
| `/update` | Update Hermes Agent to the latest version |
| `/remote-control [port] [token]` | Start web UI for remote access |
| `/help` | Show available commands |
| `/<skill-name>` | Invoke any installed skill |
@@ -220,3 +221,4 @@ Each platform has its own toolset:
- [Signal Setup](signal.md)
- [Email Setup](email.md)
- [Home Assistant Integration](homeassistant.md)
- [Web UI Setup](web.md)

214
website/docs/user-guide/messaging/web.md Normal file
View File

@@ -0,0 +1,214 @@
---
sidebar_position: 8
title: "Web UI"
description: "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`:
```bash
WEB_UI_ENABLED=true
WEB_UI_PORT=8765 # default: 8765
WEB_UI_TOKEN=mytoken # auto-generated if empty
```
Start the gateway:
```bash
hermes gateway
```
The web UI starts automatically alongside your other platforms.
---
## Step 1: Configure
Add to `~/.hermes/.env`:
```bash
# 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
```bash
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 Messages
Click the microphone button to record a voice message. The audio is transcribed via Whisper STT and sent to the agent. If voice mode is enabled (`/voice tts`), the bot replies with audio playback in the browser.
### 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:
```bash
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:
```bash
# 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`:
```bash
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.