Reset an endpoint

The MSI uninstall is intentionally non-destructive — it removes the binaries but leaves %ProgramData%\PermitUSB\ in place so a reinstall preserves event history across upgrades. That's the right default for production. It's the wrong default when you want a fresh enrollment on a machine that previously ran PermitUSB.

When you'd want to reset

  • You decommissioned the endpoint server-side and want to re-enroll the same machine as a new endpoint.
  • You're moving a test machine between tenants, environments, or dev/prod.
  • The agent is stuck in a bad credential state (repeated 401s on /agent/auth/refresh) after the dashboard purged the endpoint.
  • You're prepping a machine to hand off to a different team and want no PermitUSB residue.

What persists after MSI uninstall

LocationContents
C:\ProgramData\PermitUSB\agent.json (endpoint id, server URL, group), credentials.bin (DPAPI-encrypted refresh token), events.db (local event store), policy.bin (cached policy), agent.log
HKLM\Software\PermitUSB\BootstrapRegistry values written by the MSI from the TENANT_TOKEN / SERVER / ENDPOINT_GROUP properties. Re-read on first run if agent.json is missing.

Three ways to reset

Pick the one that fits the situation:

PathWhen to use it
msiexec /x ... PURGE_DATA=1Unattended uninstall that should also wipe data. Safest in scripted deploy / CI / fleet teardown.
Reset-PermitUSB.ps1Interactive reset on a workstation. Stops services + tray, optionally uninstalls the MSI, surfaces what was cleaned.
Manual three-line cleanupScript isn't on hand and you want a one-off teardown.

Option 1: PURGE_DATA on uninstall

The MSI exposes a PURGE_DATA property. Set it to 1 when running msiexec /x and the uninstall sequence will delete %ProgramData%\PermitUSB\ after stopping the service:

msiexec /x PermitUSB.msi /qn PURGE_DATA=1

# Or by product code (preferred for fleet-wide scripts — survives version bumps):
msiexec /x {GUID} /qn PURGE_DATA=1

Default is PURGE_DATA=0 — a normal uninstall keeps your event history and credentials so a reinstall picks up where you left off.

Option 2: reset script

We ship Reset-PermitUSB.ps1 in agent/scripts/. It stops the service and tray, optionally uninstalls the MSI, then wipes both locations above. Run from an elevated PowerShell:

Common cases

# Interactive — confirms before doing anything destructive
.\Reset-PermitUSB.ps1

# Unattended teardown including MSI uninstall (CI / scripted test reset)
.\Reset-PermitUSB.ps1 -Uninstall -Force

# Fresh enrollment but keep historical events
.\Reset-PermitUSB.ps1 -KeepEvents -Force

# Keep events AND log file (handy when filing a bug report)
.\Reset-PermitUSB.ps1 -KeepEvents -KeepLogs -Force

Flags

  • -Uninstall — also run msiexec /x to remove the MSI itself. Without this, the binaries stay.
  • -KeepEvents — preserve events.db. Useful when re-enrolling against a different tenant for testing.
  • -KeepLogs — preserve agent.log. Useful for post-mortems.
  • -Force — skip the confirmation prompt. Required for unattended use.

What happens after reset

With local state gone, the next install behaves like a first-time enrollment:

  1. Generate a fresh enrollment token at /app/enrollment.
  2. Run the msiexec command shown there on the target machine.
  3. The MSI seeds the bootstrap registry; the agent calls /agent/enroll with the new token, gets back a new endpoint id and credentials, writes them to %ProgramData%\PermitUSB\, and starts polling.

Option 3: manual cleanup

Same effect as the script, in three commands. Run as Administrator:

Stop-Service -Name PermitUSB.Agent -ErrorAction SilentlyContinue
Remove-Item -Path 'C:\ProgramData\PermitUSB' -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -Path 'HKLM:\Software\PermitUSB' -Recurse -Force -ErrorAction SilentlyContinue
Reset an endpoint — PermitUSB docs