first commit

autonomous-ai-agents/hermes-agent/references/dashboard-remote-access.md

@@ -0,0 +1,68 @@
+# Dashboard Remote Access
+
+## Problem
+Dashboard binds to 127.0.0.1:9119 by default. Accessing from a different machine (e.g., local laptop → cloud VPS) requires either SSH tunnel or insecure bind.
+
+## Recommended: SSH Port Forwarding
+```bash
+# On your local machine
+ssh -L 9119:127.0.0.1:9119 user@server-ip
+# Then open http://127.0.0.1:9119 in browser
+```
+**Pitfall (Windows):** `ssh: connect to host ... port 22: Connection timed out` — almost always a cloud security group issue. Check your cloud provider's security group / firewall rules to allow inbound TCP 22. SSH socket activation (`ssh.socket`) is enabled by default on Ubuntu; the service itself may show `inactive (dead)` — that's normal, socket activation triggers it on connection.
+
+## Password Protection (Reverse Proxy)
+
+Dashboard has **no built-in password auth**. Options:
+
+### Nginx + Basic Auth
+```bash
+sudo apt install nginx apache2-utils
+sudo htpasswd -c /etc/nginx/.htpasswd your-username
+```
+```nginx
+server {
+    listen 8080;
+    location / {
+        auth_basic "Hermes Dashboard";
+        auth_basic_user_file /etc/nginx/.htpasswd;
+        proxy_pass http://127.0.0.1:9119;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        # WebSocket support for Chat TUI
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+### Caddy (simpler config)
+```
+:8080 {
+    basicauth * {
+        username $hashed_password
+    }
+    reverse_proxy localhost:9119
+}
+```
+Generate hash: `caddy hash-password --plaintext 'your-password'`
+
+## Alternative: Insecure Bind (⚠️ exposes API keys)
+```bash
+hermes dashboard --insecure --port 9119
+# Access via http://server-ip:9119
+```
+Only use on trusted/private networks. The dashboard exposes `.env` contents including API keys. The `--insecure` flag exists because there's no built-in auth — the warning is intentional.
+
+## TUI Mode (Embedded Chat)
+```bash
+hermes dashboard --tui --no-open
+```
+Adds a Chat tab to the web UI — a browser-based `hermes --tui` via PTY/WebSocket. Useful when CLI access is inconvenient.
+
+## Common Issues
+- Multiple dashboard processes: `hermes dashboard --stop` kills all
+- Port conflict: change port with `--port 8080`
+- Gateway must be running for Kanban dispatch to work (`hermes gateway status`)
+- SSH connection timeout from Windows: check cloud security group allows inbound TCP 22