first commit

autonomous-ai-agents/hermes-agent/references/dashboard-reverse-proxy.md

@@ -0,0 +1,110 @@
+# Hermes Dashboard Reverse Proxy with Nginx
+
+## Quick Setup (Nginx + Basic Auth)
+
+### 1. Install Dependencies
+```bash
+sudo apt update && sudo apt install -y nginx apache2-utils
+```
+
+### 2. Create Password File
+```bash
+# Generate password (will prompt for password twice)
+sudo htpasswd -c /etc/nginx/.htpasswd <username>
+
+# Or non-interactive:
+echo -n '<username>:' | sudo tee /etc/nginx/.htpasswd
+openssl passwd -apr1 '<password>' | sudo tee -a /etc/nginx/.htpasswd
+```
+
+### 3. Nginx Config (`/etc/nginx/sites-available/hermes-dashboard`)
+```nginx
+server {
+    listen 80;
+    server_name <your-domain-or-ip>;  # e.g., 111.230.53.30 or hermes.example.com
+
+    location / {
+        auth_basic "Hermes Dashboard";
+        auth_basic_user_file /etc/nginx/.htpasswd;
+        
+        proxy_pass http://127.0.0.1:9119;
+        # IMPORTANT: Use "localhost" for Host header, NOT $host
+        # Dashboard validates Host header and rejects non-localhost values
+        # This causes "Invalid Host header" error if set to $host
+        proxy_set_header Host localhost;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # WebSocket support (required for Chat TUI)
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+}
+```
+
+### 4. Enable & Reload
+```bash
+sudo ln -sf /etc/nginx/sites-available/hermes-dashboard /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+### 5. Ensure Dashboard Running
+```bash
+hermes dashboard --no-open --port 9119
+```
+
+## Access
+- URL: `http://<domain-or-ip>`
+- Auth: Browser popup for username/password
+
+## Commands
+```bash
+sudo systemctl status nginx
+sudo systemctl restart nginx
+hermes dashboard --status
+hermes dashboard --stop
+```
+
+## Cleanup (Remove Reverse Proxy)
+```bash
+# Stop services
+hermes dashboard --stop
+sudo systemctl stop nginx
+sudo systemctl disable nginx
+
+# Remove config files
+sudo rm -f /etc/nginx/sites-available/hermes-dashboard
+sudo rm -f /etc/nginx/sites-enabled/hermes-dashboard
+sudo rm -f /etc/nginx/.htpasswd
+```
+
+## HTTPS (Optional)
+Use Certbot for Let's Encrypt:
+```bash
+sudo apt install certbot python3-certbot-nginx
+sudo certbot --nginx -d hermes.example.com
+```
+
+## Pitfalls
+
+### Invalid Host Header Error
+If you see `{"detail":"Invalid Host header. Dashboard requests must use the hostname the server was bound to."}`:
+- **Cause**: Nginx is passing `$host` (the public domain/IP) but Dashboard only accepts `localhost`
+- **Fix**: Change `proxy_set_header Host $host;` to `proxy_set_header Host localhost;`
+
+### Domain Requires ICP Filing (China)
+If accessing via domain in China triggers ICP filing requirement:
+- **Solution**: Use IP address directly instead of domain
+- Update `server_name` to the server's public IP
+
+### Security Notes
+- Dashboard has NO built-in password auth
+- Without reverse proxy, anyone with network access can see API keys
+- Always use reverse proxy + basic auth for remote access
+- Consider SSH port forwarding as a more secure alternative