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://agent.permitusb.com`	Origin of the agent channel. Set by the MSI; you only change this if you're pointing the agent at a non-default origin (dev / on-prem). Lives on its own DNS-only subdomain to keep installed-agent traffic out of Cloudflare's edge buffering and bot-detection.
`EndpointGroup`	`null`	Name of the endpoint group this machine belongs in. Seeded from the MSI's `ENDPOINT_GROUP` property at install time. Edit + restart the service to move this endpoint to a different group; matched case-insensitively, trimmed. Auto-syncs when the group is renamed or reassigned via the dashboard. See endpoint groups.
`PolicyPollIntervalSeconds`	`300`	How often the agent fetches policy from the cloud. Default 300 (5 min) is SaaS-friendly chatter for production. Lower it during dev for faster propagation; for the rare "I need this change applied right now" case, the tray app's Refresh policy button triggers an immediate out-of-cycle fetch.
`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://agent.permitusb.com",
  "EndpointGroup": "Engineering",
  "SyncIntervalSeconds": 5,
  "MaxBatchSize": 25,
  "PolicyPollIntervalSeconds": 300,
  "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.