From 77ca508274faf56f9155c7e3ec0791850a6f911b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 13 Jan 2026 05:31:26 +0000 Subject: [PATCH] docs: clarify dashboard token auth --- docs/start/faq.md | 14 ++++++++++++++ docs/web/dashboard.md | 6 ++++++ 2 files changed, 20 insertions(+) diff --git a/docs/start/faq.md b/docs/start/faq.md index 1ba818323..43142be88 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -87,6 +87,20 @@ The wizard can also build UI assets automatically. After onboarding, you typical The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host—nothing is fetched from the browser. +### How do I authenticate the dashboard (token) on localhost vs remote? + +**Localhost (same machine):** +- Open `http://127.0.0.1:18789/`. +- If it asks for auth, run `clawdbot dashboard` and use the tokenized link (`?token=...`). +- The token is the same value as `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`) and is stored by the UI after first load. + +**Not on localhost:** +- **Tailscale Serve** (recommended): keep bind loopback, run `clawdbot gateway --tailscale serve`, open `https:///`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy auth (no token). +- **Tailnet bind**: run `clawdbot gateway --bind tailnet --token ""`, open `http://:18789/`, paste token in dashboard settings. +- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/?token=...` from `clawdbot dashboard`. + +See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details. + ### What runtime do I need? Node **>= 22** is required. `pnpm` is recommended; `bun` is optional. diff --git a/docs/web/dashboard.md b/docs/web/dashboard.md index 1bdd70699..81d0aacc4 100644 --- a/docs/web/dashboard.md +++ b/docs/web/dashboard.md @@ -25,6 +25,12 @@ Authentication is enforced at the WebSocket handshake via `connect.params.auth` - Re-open anytime: `clawdbot dashboard` (copies link, opens browser if possible, shows SSH hint if headless). - The token stays local (query param only); the UI strips it after first load and saves it in localStorage. +## Token basics (local vs remote) + +- **Localhost**: open `http://127.0.0.1:18789/`. If you see “unauthorized,” run `clawdbot dashboard` and use the tokenized link (`?token=...`). +- **Token source**: `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`); the UI stores it after first load. +- **Not localhost**: use Tailscale Serve (tokenless if `gateway.auth.allowTailscale: true`), tailnet bind with a token, or an SSH tunnel. See [Web surfaces](/web). + ## If you see “unauthorized” / 1008 - Run `clawdbot dashboard` to get a fresh tokenized link.