mirror of
https://github.com/Finesssee/ProxyPilot.git
synced 2026-11-19 02:17:46 +00:00
5.7 KiB
5.7 KiB
WARP.md
This file provides guidance to WARP (warp.dev) when working with code in this repository.
Common commands
Go (engine + desktop binaries)
Build the main deliverables into bin/:
# Builds:
# - bin\proxypilot-engine.exe (engine)
# - bin\ProxyPilot.exe (tray app)
# - bin\ProxyPilotUI.exe (desktop dashboard)
go run .\cmd\proxypilotpack build
Run the engine directly:
# Uses config.yaml in the repo root by default
# (or pass -config <path>)
go run .\cmd\server -config .\config.yaml
Windows helpers (used for local development and Droid/Factory CLI integration):
# build engine (writes bin\proxypilot-engine.exe)
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-cliproxyapi.ps1
# start/stop/restart engine (writes logs\proxypilot-engine.{out,err}.log)
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-cliproxy.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\stop-cliproxy.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\restart-cliproxy.ps1
Package artifacts:
# Zip bundle -> dist\ProxyPilot.zip
# (includes tray, UI, engine, and config.example.yaml)
go run .\cmd\proxypilotpack package-zip
# Windows installer (Inno Setup) -> dist\ProxyPilot-Setup.exe
# Requires ISCC.exe (Inno Setup 6) available on PATH.
go run .\cmd\proxypilotpack package-inno
Docker (engine in a container):
docker compose up --build
Web UI (Vite)
The web UI lives in webui/:
cd .\webui
npm install
npm run dev # local dev server
npm run build # typecheck + build
npm run lint
Tests
Run all Go tests:
go test ./...
Run a single package:
go test .\internal\api -run TestName
Run a single test across all packages:
go test ./... -run TestName
Regression tests called out in docs:
- Droid SSE parsing:
sdk/api/handlers/openai/openai_responses_handlers_sse_done_test.go - Codex SSE done sentinel:
sdk/api/handlers/openai/openai_responses_handlers_sse_json_compat_test.go - Antigravity request shape:
internal/runtime/executor/antigravity_executor_shape_test.go
High-level architecture
Binaries (cmd/)
This repo produces multiple Go binaries:
cmd/server(engine): HTTP proxy server exposing OpenAI/Gemini/Claude-compatible endpoints; also hosts OAuth callback endpoints.cmd/cliproxytray(Windows tray app): starts/stops the engine, opens UI, toggles autostart, checks for updates.cmd/proxypilotui(Windows desktop UI): WebView2 desktop window for the Control Center; talks to the running engine and uses management endpoints.cmd/proxypilotpack: build/packaging orchestrator (build binaries intobin/, createdist/artifacts).
Engine request path (big picture)
cmd/server/main.goloads config (config.yamlor a store-backed config), decides whether to run login flows or start the server.internal/cmd/StartServicebuilds the service via the exported SDK (sdk/cliproxy.NewBuilder()) and runs it.- The HTTP server is implemented in
internal/api/server.gousing Gin:/v1/*OpenAI-compatible endpoints (plus non-/v1aliases for clients that set base URL to/v1)./v1/responseshas special streaming/SSE behavior for strict CLIs (seedocs/compat-matrix.md)./v1beta/*Gemini-compatible endpoints./v1internal:methodGemini CLI compatibility endpoint.- OAuth callbacks like
/codex/callback,/google/callback, etc. persist short-lived state for the login goroutines.
Core handler layer:
sdk/api/handlers/*contains provider-specific API adapters (OpenAI/Gemini/Claude) and schema/streaming shims.internal/api/handlers/management/*contains management endpoints mounted under/v0/management/*.
Management + desktop UX
- Management endpoints are only enabled when a secret is configured:
remote-management.secret-keyinconfig.yaml, or- environment
MANAGEMENT_PASSWORD.
- The tray app starts the engine via
internal/desktopctl.Start()and injects a per-userMANAGEMENT_PASSWORDso the desktop UX can use/v0/management/*locally. - The ProxyPilot dashboard page (
/proxypilot.html) is served localhost-only and injects the management key into the HTML so users don’t paste keys manually.
Key components:
internal/desktopctl: process management (start/stop/status), log file locations, and per-user UI state.internal/api/proxypilot_dashboard.go: local-only ProxyPilot dashboard HTML.internal/managementasset: downloads/serves the upstream management UI bundle and applies runtime text replacements for ProxyPilot branding.
Config + persistence
- Default config is
config.yaml(template:config.example.yaml). - The engine can optionally use different config/auth persistence backends based on env vars (selected in
cmd/server/main.go):- Postgres-backed store (
PGSTORE_*) - Git-backed token store (
GITSTORE_*) - Object store (
OBJECTSTORE_*)
- Postgres-backed store (
SDK embedding
The proxy can be embedded as a Go library:
sdk/cliproxyexposes a builder (NewBuilder) that wires config watching, auth, translators, and the HTTP server.docs/sdk-usage.mdshows the supported server options (middleware/router hooks, request logging overrides, management enablement).
Docs worth reading first
docs/proxypilot.md(Windows packaging + local management key behavior)docs/compat-matrix.md(client/upstream quirks; streaming/SSE gotchas; tests to protect)docs/cursor-ide.md(how Cursor expects base URL and API key behavior)docs/sdk-usage.md(how the engine is composed when embedded)