Remote access

bn serve runs the dashboard on http://localhost:4242. Add --remote and banyan also stands up an HTTPS tunnel with Bearer-token auth and prints a QR code so you can open the same dashboard from your phone in two taps.

One command

bn serve --remote

What happens:

1. The dashboard starts locally on a free port (default 4242).
2. Banyan checks for a tunnel provider (prefers cloudflared, falls back to ngrok).
3. A 32-hex token is generated (or reused if one already exists in the keychain) — every API call must carry it as Authorization: Bearer <token>.
4. The tunnel exposes the dashboard at a public https://… URL.
5. A QR code is printed in the terminal. It encodes https://…/#token=<token> — scanning it on your phone opens the dashboard already authenticated.

✓ tunnel ready: https://amber-cloud-7f3.trycloudflare.com
✓ token: 9a4f… (rotate with --rotate-token)

  ▄▄▄▄▄▄▄ ▄ ▄ ▄ ▄▄▄▄▄▄▄
  █ ▄▄▄ █ █▀▀█▀ █ ▄▄▄ █     scan to open the dashboard
  █ ███ █ ▀█▀▄  █ ███ █     on your phone
  …

How the auth works

• The token is stored in your OS keychain (security on macOS, secret-tool on Linux). It survives reboots and dashboard restarts.
• The QR code embeds the token as a URL hash fragment (#token=…) — hash fragments aren't sent to servers, so the token stays client-side until the SPA reads it on load.
• On first load the SPA reads the hash, persists the token in localStorage, strips it from the URL bar (clean address bar, no leak in screenshots), and uses it as Bearer <token> on every subsequent API call.
• Server-Sent Events (the live conversation stream) can't set arbitrary headers, so SSE accepts the token as a ?token= query string as well.

Rotating the token

bn serve --remote --rotate-token

Generates a fresh token, invalidates the old one, prints a new QR. Useful if you've shared a QR by accident or want a clean break.

Pick the tunnel provider

bn serve --remote --tunnel cloudflared
bn serve --remote --tunnel ngrok

Auto-detect chooses cloudflared if both are installed. Cloudflare quick tunnels need no account; ngrok needs an auth token configured locally.

Install:

• Cloudflared: brew install cloudflared (macOS) — see Cloudflare docs for other OSes.
• ngrok: brew install ngrok && ngrok config add-authtoken <yours>.

Why this matters

The whole point of banyan is running many agents in parallel — and agents take a while. You don't want to be tethered to your desk waiting for them. With --remote you can step away, check the pipeline progress on your phone, jump back into a live conversation with one of the agents, and approve a plan from a café.