diff --git a/understand-anything-plugin/skills/understand-dashboard/SKILL.md b/understand-anything-plugin/skills/understand-dashboard/SKILL.md index ab8842a..890aef0 100644 --- a/understand-anything-plugin/skills/understand-dashboard/SKILL.md +++ b/understand-anything-plugin/skills/understand-dashboard/SKILL.md @@ -77,21 +77,57 @@ Start the Understand Anything dashboard to visualize the knowledge graph for the cd && pnpm --filter @understand-anything/core build ``` -5. Start the Vite dev server pointing at the project's knowledge graph: +5. **Detect whether this is a remote / headless session.** A localhost-only bind + (the default) cannot be reached from the user's browser when Vite runs on a + different machine, and Vite rejects domain-name `Host` headers with + `Blocked request. This host ("…") is not allowed.` Check for a remote session: + ```bash + [ -n "$SSH_CONNECTION" ] || [ -n "$SSH_TTY" ] || [ -n "$SSH_CLIENT" ] && echo remote || echo local + ``` + - If the result is `local`, skip to step 6 and launch with defaults. + - If the result is `remote`, **ask the user** which host they will open the + dashboard from, e.g.: + ``` + It looks like you're running on a remote machine. Which hostname or IP + will you open the dashboard from in your browser? + (e.g. mybox.example.com or 203.0.113.5 — press enter to keep localhost-only) + ``` + Remember their answer as ``. If they skip / press enter, treat + this as a local session and launch with defaults. + +6. Start the Vite dev server pointing at the project's knowledge graph. + + **Local session** (default — binds to localhost only): ```bash cd && GRAPH_DIR= npx vite --host 127.0.0.1 ``` + + **Remote session** (user provided `` in step 5): + ```bash + cd && GRAPH_DIR= \ + UNDERSTAND_HOST=0.0.0.0 \ + UNDERSTAND_ALLOWED_HOSTS= \ + npx vite + ``` + `UNDERSTAND_HOST=0.0.0.0` accepts connections from outside localhost, and + `UNDERSTAND_ALLOWED_HOSTS` whitelists the `Host` header so Vite stops blocking + it. The one-time access token still gates every data endpoint. + Run this in the background so the user can continue working. -6. **Capture the access token URL from the server output.** The Vite server prints a line like: +7. **Capture the access token URL from the server output.** The Vite server prints a line like: ``` 🔑 Dashboard URL: http://127.0.0.1:?token= ``` - Extract the full URL including the `?token=` parameter. The token is required to access the knowledge graph data — without it the dashboard will show an "Access Token Required" gate. + Extract the `?token=` value — it is required to access the knowledge graph + data; without it the dashboard shows an "Access Token Required" gate. The + printed line always shows `127.0.0.1`; for a remote session substitute + `` for the host portion when reporting the URL. -7. Report to the user, including the full tokenized URL: +8. Report to the user, including the full tokenized URL (use `` + instead of `127.0.0.1` for a remote session): ``` - Dashboard started at http://127.0.0.1:?token= + Dashboard started at http://:?token= Viewing: /.understand-anything/knowledge-graph.json The dashboard is running in the background. Press Ctrl+C in the terminal to stop it.