# Windows UI for ProxyPilot — Spec (Wails + Tauri) This is the Windows-specific portion of the desktop UI plan. Shared (cross-platform) decisions and architecture live in `docs/desktop-ui-spec.md`. ## Goals - Provide a Windows-friendly way to run and manage `ProxyPilot` without PowerShell. - Surface request/log diagnostics to reduce “prompt too long” + debugging pain. - Support two desktop shells over time: - Primary: Wails (Go backend + web UI) - Secondary/experimental: Tauri (Rust + web UI) - Share logic via a Go control layer so features don’t fork. ## Non-goals (v1) - Replacing the existing Management API UI shipped with the server. - Full cross-platform parity (macOS/Linux can come later). - Full OAuth flows inside the desktop UI (v1 can “open browser” and show status). - Becoming an agent/IDE: this is a small controller + diagnostics utility. ## Product decisions (to avoid bikeshedding) - v1 ships as Wails. - Tauri is optional later; it should reuse the same control layer via a helper CLI. - The UI controls an existing `proxypilot-engine.exe` (built by the UI or already present). - The UI should not require elevated privileges and should default to localhost-only behavior. ## Personas / Use-cases - “I just want it running”: start/stop, see port, see health. - “I need to debug”: view logs, open request logs, copy diagnostics. - “I’m configuring tools”: show local base URL, API key hints, and quick-copy snippets. - “I want it to launch on login”: enable/disable autostart (per-user). ## UX requirements - Tray-first: app sits in the system tray with minimal friction. - Single click status: Running/Stopped + port + quick actions. - No admin required for normal operation. - Clear failure reasons: missing config, port in use, binary missing, auth dir missing. ## Functional requirements (v1) ### Process control - Build (optional): build `cmd/server` into `bin/proxypilot-engine.exe`. - Start: - Uses a selectable config path (default: repo `config.yaml` if present). - Writes logs to `logs/proxypilot-engine.out.log` and `logs/proxypilot-engine.err.log`. - Stop: - Prefer graceful stop; fallback to kill process if needed. - Restart. - Detect running instance: - PID-based if started by UI, plus best-effort discovery by listening port. - If an instance is running but not owned by the UI, show “External” and offer read-only “Attach” (don’t blindly kill it). ### Status & health - Show: - port (from config or detection) - reachable status via `GET http://127.0.0.1:/v1/models` (or a future `/healthz`) - last start time and PID (when known) - Buttons: - Open Management UI (browser) - Open logs folder - Copy base URL (`http://127.0.0.1:` and optionally `/v1`) ### Config - Config path selector (browse + remember last choice). - Validate YAML on save (or warn on parse failure). - Minimal editor: - open in external editor, and/or inline text editor with Save. - Safe defaults: - warn if management routes are remotely accessible. ### Autostart (Windows) - Enable/disable per-user startup on Windows. - Backend supports: - registry `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` - scheduled task fallback (optional; clearly labeled) ### Quick-copy snippets (v1) - Show ready-to-paste snippets: - `OPENAI_BASE_URL=http://127.0.0.1:/v1` - `OPENAI_API_KEY=` - curl sanity check for `GET /v1/models` ### Diagnostics / support bundle (v1.1) - One-click “Copy diagnostics”: - version, config path, port, PID, last 200 lines of logs - recent request logs list (or last N request IDs) ## Shared Go control layer (Windows notes) Wails and Tauri should both call the same operations (process management, config, logs, autostart, health checks). See `docs/desktop-ui-spec.md` for the proposed package/API shape. Windows-specific notes: - Persist UI state in `%LOCALAPPDATA%/ProxyPilot/ui-state.json`. - Prefer discover-by-port over discover-by-process-name. - When opening folders/URLs, use native Windows shell APIs (no admin). ## Wails app (primary) — MVP ### Packaging - Ship `ProxyPilot.exe` with embedded web UI assets. - Bundle or download `proxypilot-engine.exe` (open decision). ### Screens - Tray menu: - Start / Stop / Restart - Open UI - Open logs - Quit - Main window: - Status card (Running/Stopped, port, last error) - Buttons: Start/Stop/Restart, Open Management UI, Open Logs - Config path selector + Open config - Autostart toggle - Copy snippets section (base URL + key + curl check) ### First-run UX - If no config path is set: - Detect `config.yaml` in common locations (repo root, `%LOCALAPPDATA%/ProxyPilot/`, user home). - Offer “Use detected config” or “Browse…”. - If no API key is configured: - Offer “Generate local key” (writes to config) or “Open config” guidance. ## Tauri app (secondary) — MVP ### Purpose - Evaluate smaller footprint distribution vs Wails. - Prototype a more native-feeling tray + notifications. ### Integration options - Option A (recommended): Tauri calls a helper CLI (`cliproxyctl.exe`). - Option B: Tauri starts a small local HTTP control server. ## Security considerations - Default to localhost-only assumptions. - Don’t display or log API keys unless explicitly requested. - When enabling autostart, show what command will run. - Avoid writing outside the user profile unless configured. ## Open decisions - Where config lives by default (repo-local vs user config dir). - Whether UI bundles the server binary or manages an existing install. - Whether to add a stable `/healthz` endpoint for fast health checks. - Whether “Generate local key” should mutate `config.yaml` or use a UI-only key store. - Whether the UI should surface auth selection state (primary/backup) for providers like `antigravity`. ## Acceptance criteria (v1) - Installing and launching the app shows a tray icon and a status window. - Start/Stop/Restart works reliably across app restarts (PID state persisted). - Health check distinguishes: - process running but endpoint not reachable - endpoint reachable with `GET /v1/models` returning 200 - Open logs opens the correct folder. - Copy base URL copies `http://127.0.0.1:` (and optionally `/v1`).