Hermes Dashboard Reverse Proxy with Nginx

Quick Setup (Nginx + Basic Auth)

1. Install Dependencies

sudo apt update && sudo apt install -y nginx apache2-utils

2. Create Password File

# 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`)

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

sudo ln -sf /etc/nginx/sites-available/hermes-dashboard /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

5. Ensure Dashboard Running

hermes dashboard --no-open --port 9119

Access

URL: http://<domain-or-ip>
Auth: Browser popup for username/password

Commands

sudo systemctl status nginx
sudo systemctl restart nginx
hermes dashboard --status
hermes dashboard --stop

Cleanup (Remove Reverse Proxy)

# 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:

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

3.2 KiB Raw Permalink Blame History