PatchPilot
Get Started
User guideAgents

Install the agent on Windows

You need an enrollment token. The portal shows the commands below with your address and token filled in; copy them from there.

Install

  1. Open PowerShell as administrator (right-click, Run as administrator).

  2. Paste the three lines from the portal:

    powershell
    $env:PATCHPILOT_SERVER_URL='https://YOUR-PORTAL'
$env:PATCHPILOT_ENROLLMENT_TOKEN='ppe_…'
iwr -useb https://YOUR-PORTAL/install.ps1 | iex

The installer:

  1. downloads the agent from your portal and checks its SHA-256 checksum, refusing to install on a mismatch;
  2. installs it to C:\Program Files\PatchPilot\patchpilot-agent.exe;
  3. creates and starts the Windows service PatchPilot agent (PatchPilotAgent), set to start automatically;
  4. waits up to 60 seconds for the host to enroll, then deletes the token from the host.

The token is kept in a file only Administrators and SYSTEM can read until enrollment, and is never passed on a command line.

The winget question

PatchPilot updates third-party programs (Chrome, 7-Zip, Zoom and many more) through winget, Microsoft's package manager. Most Windows 10 and 11 machines already have it; many servers do not.

If the host has no winget, the installer asks:

text
patchpilot: install winget on this host? [Y/n]
  • Yes: the agent installs winget in the background once it is running (about 100 MB, from Microsoft's winget release on GitHub). Third-party programs are then updated through winget.
  • No: PatchPilot updates only the programs in its own catalogue: Chrome, Firefox, 7-Zip, Notepad++, Git, VLC and Visual Studio Code.

Windows updates themselves come from Windows Update either way.

Installing without anyone to answer

For scripted installs (Intune, GPO, RMM tools), answer in advance by adding one line before the others:

powershell
$env:PATCHPILOT_WINGET='install'   # or 'skip'

With no answer and nobody at the keyboard, the installer chooses skip, so it never downloads 100 MB onto a server unasked. Running the installer again keeps the earlier answer unless you set PATCHPILOT_WINGET again.

Checking the agent

powershell
Get-Service PatchPilotAgent
Get-Content C:\ProgramData\PatchPilot\agent.log -Tail 50 -Wait

Files on the host:

Path What it is
C:\Program Files\PatchPilot\patchpilot-agent.exe The agent
C:\ProgramData\PatchPilot\state.json The host's own credential, readable by Administrators and SYSTEM only
C:\ProgramData\PatchPilot\agent.log The agent's log

If it does not enroll

Message What to do
"run this in an elevated PowerShell (Run as administrator)" Open PowerShell with Run as administrator
"download failed: is … reachable from this host?" The host cannot reach your portal on port 443. Check DNS, firewall and proxy
"the agent did not enrol within 60s" Check C:\ProgramData\PatchPilot\agent.log. Usually the token has expired, reached its use limit, or the host is outside the token's allowed networks or hostnames. Enrollment attempts in the portal shows the reason
"32-bit Windows is not supported" The agent needs 64-bit Windows

If the token required approval, the host waits under Waiting for approval on the Enrollment page until an administrator approves it.

Running the installer again

Running it again on an enrolled host upgrades the agent and keeps the host's identity; only PATCHPILOT_SERVER_URL is needed. See Upgrade agents.

Next