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

Location	Contents
`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\Bootstrap`	Registry 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:

Path	When to use it
`msiexec /x ... PURGE_DATA=1`	Unattended uninstall that should also wipe data. Safest in scripted deploy / CI / fleet teardown.
`Reset-PermitUSB.ps1`	Interactive reset on a workstation. Stops services + tray, optionally uninstalls the MSI, surfaces what was cleaned.
Manual three-line cleanup	Script 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

Reset-PermitUSB.ps1 stops the service and tray, optionally uninstalls the MSI, then wipes both locations above. Download it from the dashboard's Agent releases page (the "Download reset script" button), copy it onto the target machine, then 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:

Generate a fresh enrollment token at /app/enrollment.
Run the msiexec command shown there on the target machine.
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