Files
ProxyPilot/docs/desktop-app-build-process.md
Finessse 45289603b9 refactor: rename cliproxytray → proxypilot-tray
- Rename cmd/cliproxytray to cmd/proxypilot-tray
- Update all script references
- Update workflow and docs
2026-01-12 04:43:58 +07:00

9.5 KiB

ProxyPilot CLI + Tray Build Process

Documentation of the CLI and system tray application build and release process.

Overview

ProxyPilot uses a CLI + system tray architecture:

  • proxypilot.exe - CLI executable with all proxy functionality
  • ProxyPilot.exe - System tray app that manages the CLI process and provides quick access to controls

The dashboard is accessed via web browser at http://127.0.0.1:<port>/proxypilot.html.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     ProxyPilot System                           │
│                                                                  │
│  ┌─────────────────────┐      ┌─────────────────────────────┐   │
│  │   ProxyPilot.exe    │      │      proxypilot.exe         │   │
│  │   (System Tray)     │─────▶│      (CLI / Engine)         │   │
│  │                     │      │                             │   │
│  │  - Start/Stop       │      │  - Proxy Engine (port 8317) │   │
│  │  - Open Dashboard   │      │  - Web Dashboard Server     │   │
│  │  - Copy API URL     │      │  - Provider Auth Mgmt       │   │
│  │  - Autostart toggle │      │  - Routing Engine           │   │
│  └─────────────────────┘      └─────────────────────────────┘   │
│                                                                  │
│                         ┌─────────────────────┐                  │
│                         │   Web Browser       │                  │
│                         │  (Dashboard UI)     │                  │
│                         │  proxypilot.html    │                  │
│                         └─────────────────────┘                  │
└─────────────────────────────────────────────────────────────────┘

CLI + Tray Separation

The architecture separates concerns:

proxypilot.exe (CLI):

  • All proxy engine functionality
  • Serves web dashboard at /proxypilot.html
  • Can run standalone from command line
  • Supports all CLI flags (--help, --setup-claude, etc.)

ProxyPilot.exe (Tray):

  • Lightweight system tray wrapper
  • Manages CLI process lifecycle (start/stop/restart)
  • Opens dashboard in default browser
  • Provides quick-access menu

Benefits of CLI + tray architecture:

  • Flexibility: Use CLI directly or via tray app
  • No WebView2 dependency: Dashboard runs in any browser
  • Simpler debugging: Inspect network/console in browser DevTools
  • Cross-platform dashboard: Same web UI works on all platforms

Build Process

Prerequisites

# Required tools
go install github.com/josephspurrier/goversioninfo/cmd/goversioninfo@latest

Inno Setup 6 must be installed for creating the Windows installer.

Step 1: Build Web UI Assets

cd webui
npm install
npm run build

This generates webui/dist/ with the dashboard assets that are served by the CLI at /proxypilot.html.

Step 2: Create Multi-Resolution Icon

The icon must have multiple sizes for proper Windows display (16px to 256px):

from PIL import Image

img = Image.open('static/icon.png')
if img.mode != 'RGBA':
    img = img.convert('RGBA')

sizes = [(16,16), (24,24), (32,32), (48,48), (64,64), (128,128), (256,256)]
img.save('static/icon.ico', format='ICO', sizes=sizes)

Copy to tray icon location:

cp static/icon.ico internal/trayicon/icon.ico

Step 3: Generate Windows Resource Files

Generate .syso files for embedding icons in executables:

cd cmd/proxypilot-tray
goversioninfo -icon="../../static/icon.ico"

This creates resource.syso files that Go automatically includes during build.

Step 4: Build Executables

# Build CLI executable
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o dist/proxypilot.exe ./cmd/server

# Build tray app (with -H windowsgui to hide console)
GOOS=windows GOARCH=amd64 go build -ldflags="-s -w -H windowsgui" -o dist/ProxyPilot.exe ./cmd/proxypilot-tray

Step 5: Build Installer

# Using Inno Setup
"C:\Users\FSOS\AppData\Local\Programs\Inno Setup 6\ISCC.exe" installer/proxypilot.iss

Output: dist/ProxyPilot-0.1.0-Setup.exe

Key Files

Version Info Configuration

cmd/proxypilot-tray/versioninfo.json

{
  "FixedFileInfo": {
    "FileVersion": {"Major": 0, "Minor": 1, "Patch": 0, "Build": 0},
    "ProductVersion": {"Major": 0, "Minor": 1, "Patch": 0, "Build": 0}
  },
  "StringFileInfo": {
    "FileDescription": "ProxyPilot System Tray",
    "ProductName": "ProxyPilot",
    "ProductVersion": "0.1.0"
  },
  "IconPath": "../../static/icon.ico"
}

Tray Process Manager

cmd/proxypilot-tray/engine.go - Manages the CLI process:

  • Spawns/stops proxypilot.exe subprocess
  • Monitors process health
  • Passes configuration and management password

Tray Icon Embedding

internal/trayicon/ico.go

package trayicon

import (
    _ "embed"
)

//go:embed icon.ico
var proxyPilotICO []byte

func ProxyPilotICO() []byte {
    return proxyPilotICO
}

Installer Script

installer/proxypilot.iss - Inno Setup script that:

  • Installs proxypilot.exe and ProxyPilot.exe to %LOCALAPPDATA%\ProxyPilot
  • Creates Start Menu shortcut
  • Adds optional Windows startup entry
  • Copies config.example.yaml and creates config.yaml on first install
  • Uses ProxyPilot icon for installer and shortcuts

System Tray Menu

Simplified flat menu structure:

┌─────────────────────┐
│ Open Dashboard      │  → Opens browser to proxypilot.html
├─────────────────────┤
│ Start/Stop          │  → Toggle proxy engine (CLI process)
│ Copy API URL        │  → Copies http://127.0.0.1:8317/v1
├─────────────────────┤
│ Quit                │  → Stop engine and exit
└─────────────────────┘

Release Process

Create Release on GitHub

# Tag the release
git tag v0.1.0
git push origin v0.1.0

# Create release with assets
gh release create v0.1.0 \
  --title "ProxyPilot v0.1.0" \
  --notes "Release notes here" \
  dist/ProxyPilot-0.1.0-Setup.exe \
  dist/ProxyPilot.exe \
  config.example.yaml

Update Existing Release

# Delete old asset
gh release delete-asset v0.1.0 ProxyPilot.exe --yes

# Upload new asset
gh release upload v0.1.0 dist/ProxyPilot.exe

Troubleshooting

Icon Not Showing in File Explorer

  1. Ensure icon.ico has 256x256 size (required for Windows)
  2. Clear Windows icon cache: ie4uinit.exe -show
  3. Verify resource.syso was generated after icon update
  4. Rebuild the executable

Dashboard Not Loading in Browser

  1. Ensure the CLI process is running (check tray status)
  2. Verify the port is correct: http://127.0.0.1:8317/proxypilot.html
  3. Check for port conflicts with another application

Tray Icon Shows Wrong Image

  1. Check internal/trayicon/icon.ico is the correct file
  2. Rebuild the tray app to re-embed the icon
  3. Restart the application

Engine Not Starting

  1. Check if port 8317/8318 are already in use
  2. Review logs in %LOCALAPPDATA%\ProxyPilot\logs\
  3. Ensure config.yaml is valid YAML

File Structure

ProxyPilot/
├── cmd/
│   ├── server/
│   │   └── main.go              # CLI entry point
│   └── proxypilot-tray/
│       ├── main_windows.go      # Tray app entry point
│       ├── engine.go            # CLI process manager
│       ├── versioninfo.json     # Version/icon config
│       └── resource.syso        # Compiled resources
├── internal/
│   └── trayicon/
│       ├── ico.go               # Embeds icon.ico
│       └── icon.ico             # ProxyPilot logo (multi-res)
├── static/
│   ├── icon.ico                 # Source icon (7 sizes)
│   └── icon.png                 # Original PNG logo
├── webui/
│   ├── src/                     # React dashboard source
│   └── dist/                    # Built assets (served by CLI)
├── installer/
│   └── proxypilot.iss           # Inno Setup script
└── dist/                        # Distribution files
    ├── proxypilot.exe           # CLI executable
    └── ProxyPilot.exe           # Tray app

Version History

  • v0.3.0 (2025-12-30) - CLI + Tray architecture

    • Removed WebView2 dependency
    • Dashboard served by CLI, opened in browser
    • Tray app manages CLI subprocess
    • Simplified deployment and debugging
  • v0.2.0 (2025-12-27) - Single-binary architecture

    • Embedded proxy engine runs in-process
    • Removed separate proxypilot-engine.exe
    • Reduced total size from ~46MB to ~29MB
    • Faster startup with no process spawning
  • v0.1.0 (2025-12-27) - Initial release

    • System tray with minimal menu
    • Multi-resolution icon support
    • Single-file Windows installer