Files
ProxyPilot/WARP.md

5.7 KiB
Raw Permalink Blame History

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 into bin/, create dist/ artifacts).

Engine request path (big picture)

  1. cmd/server/main.go loads config (config.yaml or a store-backed config), decides whether to run login flows or start the server.
  2. internal/cmd/StartService builds the service via the exported SDK (sdk/cliproxy.NewBuilder()) and runs it.
  3. The HTTP server is implemented in internal/api/server.go using Gin:
    • /v1/* OpenAI-compatible endpoints (plus non-/v1 aliases for clients that set base URL to /v1).
    • /v1/responses has special streaming/SSE behavior for strict CLIs (see docs/compat-matrix.md).
    • /v1beta/* Gemini-compatible endpoints.
    • /v1internal:method Gemini 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-key in config.yaml, or
    • environment MANAGEMENT_PASSWORD.
  • The tray app starts the engine via internal/desktopctl.Start() and injects a per-user MANAGEMENT_PASSWORD so 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_*)

SDK embedding

The proxy can be embedded as a Go library:

  • sdk/cliproxy exposes a builder (NewBuilder) that wires config watching, auth, translators, and the HTTP server.
  • docs/sdk-usage.md shows 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)