# Desktop UI (ProxyPilot) — Shared Spec (Windows first) This doc captures shared architecture and product decisions for a desktop “controller app” that manages a local `ProxyPilot` instance. OS-specific details live in: - Windows: `docs/windows-ui-spec.md` - macOS (future): `docs/macos-ui-spec.md` (not yet) ## What we’re building A small tray-first desktop app that can: - start/stop/restart the local proxy engine (ProxyPilot Engine) - show health + port + “copy base URL” snippets for IDE/agentic CLIs - surface logs/request diagnostics to debug issues like 400/429, “prompt too long”, streaming quirks It is not a full replacement for the server’s Management UI; it’s a launcher + diagnostics tool. ## Two-shell strategy (Wails + Tauri) We can support both Wails and Tauri without forking business logic by standardizing on a single control interface. ### Primary shell: Wails (Go) - Pros: simplest integration with existing Go codebase, easiest to ship v1 fast. - Architecture: Wails UI ↔ Go control layer (in-process). ### Secondary shell: Tauri (Rust) - Pros: smaller footprint, strong native tray/window tooling, good distribution story. - Architecture (recommended): Tauri UI ↔ helper CLI ↔ Go control layer. - Tauri calls `cliproxyctl` (or similar) as a subprocess. - Benefits: no Rust↔Go FFI, no duplicated process logic, easy testing. ## Shared control interface ### Go package - `internal/desktopctl` - Pure Go logic for process management, config reading/writing, health, logs, autostart primitives. - No UI dependencies. ### Suggested helper CLI (used by Tauri and power users) - `cmd/cliproxyctl` - `cliproxyctl status --config ` - `cliproxyctl start --config ` - `cliproxyctl stop` - `cliproxyctl restart --config ` - `cliproxyctl diag --config --out ` Wails can call `internal/desktopctl` directly; Tauri can call `cliproxyctl`. ## Feature scope (v1) ### Core controls - Start/Stop/Restart the proxy engine. - Detect if a proxy is already running: - If owned by UI: show as “Managed”. - If not owned: show as “External” and offer “Attach” (read-only) vs “Stop anyway” behind a confirmation. ### Health - Health check: `GET http://127.0.0.1:/healthz`. - Show last successful check time and last error message. ### Config - Config path chooser + remember last choice. - “Open config” action (external editor). - Validate YAML on save (or show parse error). ### Logs / request diagnostics - Open logs folder. - Tail last N lines of `proxypilot-engine.out.log` and `proxypilot-engine.err.log`. - “Copy diagnostics” button that includes: - app version, proxy version - config path, port, pid - last error + last N log lines - pointers to recent request logs ### Quick-copy snippets - `OPENAI_BASE_URL=http://127.0.0.1:/v1` - `OPENAI_API_KEY=` - Minimal curl sanity checks. ## Nice-to-haves (v1.1+) - “Recent requests” viewer (parse `logs/v1-*.log`): - list request IDs, status, provider, model, auth label, latency - click to open the log file at the relevant section - Surface auth status: - list loaded auth files + provider + account email (when available) - show “cooling down” vs “active” - optionally display primary/backup preference (e.g. `antigravity`) - “Safe config wizard”: - toggle localhost-only management - add/generate local dev API key - Update mechanism (self-update) and server binary update strategy. ## Security / safety rules - Default to localhost-only assumptions. - Don’t display or log API keys unless user explicitly reveals/copies them. - Autostart toggles must show exactly what command will run. - Avoid writing outside user profile by default. ## Cross-platform notes Split OS-specific operations behind small interfaces in `internal/desktopctl`: - Process operations (spawn, signal/terminate, pid discovery) - Autostart - “Open folder” / “Open URL” Windows and macOS implementations can live in separate files via Go build tags: - `*_windows.go` - `*_darwin.go` ## Open questions - Should the desktop app bundle the engine binary, or manage an existing install? - Do we want a dedicated “desktop control” HTTP endpoint in the proxy (vs local process control only)?