- Rename cmd/cliproxytray to cmd/proxypilot-tray - Update all script references - Update workflow and docs
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.exesubprocess - 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.exeandProxyPilot.exeto%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
- Ensure icon.ico has 256x256 size (required for Windows)
- Clear Windows icon cache:
ie4uinit.exe -show - Verify resource.syso was generated after icon update
- Rebuild the executable
Dashboard Not Loading in Browser
- Ensure the CLI process is running (check tray status)
- Verify the port is correct:
http://127.0.0.1:8317/proxypilot.html - Check for port conflicts with another application
Tray Icon Shows Wrong Image
- Check internal/trayicon/icon.ico is the correct file
- Rebuild the tray app to re-embed the icon
- Restart the application
Engine Not Starting
- Check if port 8317/8318 are already in use
- Review logs in
%LOCALAPPDATA%\ProxyPilot\logs\ - 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