docs(FN-2524): add remote access operator runbook

- Add docs/remote-access.md as the canonical runbook for dashboard, TUI, and headless remote access operations
- Document provider prerequisites, lifecycle restore gates, and status/diagnostic semantics for remote tunnel management
- Add remote auth security guidance for tokenized URLs/QR payloads and include troubleshooting-oriented API flow references
- Cross-link the runbook from docs index and related architecture, CLI, dashboard, getting-started, and settings docs
This commit is contained in:
Fusion
2026-04-26 05:38:18 -07:00
committed by gsxdsm
parent e5ed696922
commit 5ffa1eeba2
7 changed files with 334 additions and 0 deletions

View File

@@ -87,6 +87,8 @@ Remote actions support:
- Short-lived token generation with TTL input and expiry display
- URL + QR hand-off (always shows full authenticated URL)
> ⚠️ Remote URL/QR payloads include tokenized query data. Treat them like credentials and avoid sharing them in screenshots/chat/logs. Prefer short-lived links for ad-hoc phone login.
Remote action keys in Settings detail pane:
- `C` activate selected provider
- `V` start tunnel
@@ -231,6 +233,20 @@ When remote access is enabled/configured, the headless server exposes `/api/remo
control/status endpoints and applies the same hybrid token validation rules for
remote routes (persistent token + optional short-lived token registry).
Headless operators should use the same lifecycle/API flow as dashboard mode:
- `POST /api/remote/provider/activate`
- `POST /api/remote/tunnel/start`
- `POST /api/remote/tunnel/stop`
- `GET /api/remote/status`
- `POST /api/remote-access/auth/login-url`
`GET /remote-login?rt=<token>` is intentionally public for phone-link handoff,
but token validity is still enforced server-side.
For end-to-end setup, risk guidance, and troubleshooting, see
**[docs/remote-access.md](./remote-access.md)**.
For programmatic consumers, these endpoints map to the engine tunnel manager contract:
- `getStatus()` for current snapshot
- `start(provider, config)` / `stop()` / `switchProvider(...)`