Windows
Install, first run, PATH, services, upgrade, repair, and uninstall PortPilot on Windows 10 and 11 x64.
Prerequisites
- Windows 10 or 11 x64 (ARM64 is not supported)
- Administrator permission to install
- After install, a standard user can run PortPilot Desktop and
portpilot - Microsoft Edge WebView2 Runtime for Desktop — Setup installs it if missing
Install
- Download the MSI from Download (
PortPilot-Setup-x64-vX.Y.Z.msi). - Run it. Finish can launch PortPilot. Wait a few seconds if the first window says it cannot reach the agent.
- Open a new terminal before using
portpilot(PATH updates apply to new shells).
What is installed (per-machine):
| Item | Location |
|---|---|
Agent service PortPilotAgent | %ProgramFiles%\PortPilot\agent\ |
Helper service PortPilotHelper | %ProgramFiles%\PortPilot\helper\ |
| Desktop | %ProgramFiles%\PortPilot\desktop\ |
CLI portpilot.exe | %ProgramFiles%\PortPilot\cli\ on PATH |
| Data | %ProgramData%\PortPilot |
Services run as LocalSystem, auto-start, restart on failure. Helper starts first; Agent depends on it. Closing the tray app does not stop the agent.
First run
The desktop asks you to Enter pairing code or Use locally. Local use skips the cloud. Pairing stays available under Machine.
portpilot --version
portpilot --help
portpilot status
portpilot pairExpected: services PortPilotAgent and PortPilotHelper are Running; portpilot status works in a new terminal; Desktop shows Ports after a few seconds.
Upgrade
Run the newer MSI. Do not uninstall first. Services stop, binaries replace, then services start. %ProgramData%\PortPilot is kept (identity, database, pairing).
Repair
Settings → Apps → PortPilot → Modify / Repair. Repair restores missing binaries, services, PATH, and shortcuts. It does not delete machine identity. If WebView2 is missing, Setup may install the runtime again.
Uninstall
Settings → Apps → PortPilot → Uninstall (or Add/Remove Programs). Binaries, services, Start Menu, and PATH are removed. Data is kept so a reinstall resumes the same machine id.
To delete identity, database, pairing, and logs (cannot be undone), run the elevated uninstall script with purge from the packaging docs you received with a source checkout — typical installs should leave ProgramData in place.
Windows troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| Installer failed | SmartScreen, missing admin, WebView2 download failed on Desktop-only path | Run as Administrator; allow the publisher; retry with network if Desktop needs WebView2 |
| Service not running | Boot race, failed upgrade | Get-Service PortPilotHelper, PortPilotAgent; Start them; Repair |
| UI cannot connect to agent | Agent still starting, token ACL | Wait a few seconds; Retry / Restart agent; confirm ProgramData token is readable |
portpilot not found | Old terminal, PATH | Open a new cmd/PowerShell; where.exe portpilot |
| Permission / Access Denied on token | ACL limited to install user + Admins (not every Windows account) | Use the account that installed PortPilot, or an Administrator; restart PortPilotHelper, then Repair |
| Firewall mutate fails | Not Pro, or helper down | Firewall; confirm Helper running |
| Machine not pairing / offline | Code expired, no outbound HTTPS, agent down | Pairing; portpilot doctor |
| Upgrade problems | Running the same ProductVersion | Use a newer versioned MSI; do not uninstall first |
| Uninstall left CLI on PATH | Rare stale PATH | Repair then uninstall, or remove ...\PortPilot\cli from system PATH |
Logs: %ProgramData%\PortPilot\logs\. Do not send local.token or pairing codes to support.