Agent configuration

Once an endpoint has enrolled, all runtime config lives in a single JSON file at:

C:\ProgramData\PermitUSB\agent.json

Edit the file (as Administrator) and restart the PermitUSB.Agent service for the new values to take effect. The file is written by the agent on first run with sensible defaults; you only edit it when you want to change something.

Available knobs

Field	Default	What it does
`ApiUrl`	`https://permitusb.com`	Origin of the cloud API. Set by the MSI; you only change this if you're pointing the agent at a non-default origin (dev / on-prem).
`PolicyPollIntervalSeconds`	`60`	How often the agent fetches policy from the cloud. Lower = faster propagation of dashboard changes; higher = less network chatter.
`SyncIntervalSeconds`	`5`	How often event batches are drained to `/agent/events`.
`MaxBatchSize`	`25`	Cap on events per drain cycle.
`WatchdogIntervalSeconds`	`30`	How often the watchdog re-disables tampered devices.
`MaxStalenessDays`	`7`	How long the agent will use a cached policy before falling back to default-block when offline.

Editing the file

Open C:\ProgramData\PermitUSB\agent.json in any editor (with administrator rights). Example with PowerShell:

# As Administrator
notepad 'C:\ProgramData\PermitUSB\agent.json'

# After saving, restart the service so the new value takes effect
Restart-Service -Name PermitUSB.Agent

A typical file looks like this:

{
  "ApiUrl": "https://permitusb.com",
  "SyncIntervalSeconds": 5,
  "MaxBatchSize": 25,
  "PolicyPollIntervalSeconds": 60,
  "WatchdogIntervalSeconds": 30,
  "MaxStalenessDays": 7
}

Fleet deployment

For pushing config to many endpoints at once:

Group Policy: Computer Configuration → Preferences → Windows Settings → Files. Configure a copy of agent.json to land at %ProgramData%\PermitUSB\agent.json.
Intune: deploy a Win32 app with a remediation script that writes the file to $env:ProgramData\PermitUSB\agent.json and restarts the service.
Ansible / Chef / Puppet: standard copy / file resource onto the path, with a service-restart handler.

Pulling a policy change without waiting for the next poll

Right-click the PermitUSB tray icon → Refresh policy. The tray asks the agent to do an immediate cloud fetch + reconcile, no service restart required. Useful when you make a change in the dashboard and want to verify it on a test machine right away without editing agent.json.

What about the registry?

The MSI writes a few values under HKLM\Software\PermitUSB\Bootstrap (ApiUrl, EnrollmentToken, EndpointGroup) at install time. The agent reads these once on first boot to handshake the initial enrollment, then writes agent.json. After that the registry is never consulted again — editing those values post-enrollment has no effect. agent.json is canonical.