Agent configuration

Once an endpoint has enrolled, all runtime config lives in a single JSON file. Edit it as Administrator and restart the PermitUSB.Agent service for new values to take effect.

Operationsagent.json

C:\ProgramData\PermitUSB\agent.json

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. Change only to point at a non-default origin. It lives on its own DNS-only subdomain to keep installed-agent traffic out of edge buffering and bot detection.
EndpointGroup	null	Name of the group this machine belongs in, seeded from the MSI at install. Edit and restart to move the endpoint. Matched case-insensitively and trimmed, and auto-syncs when the group is renamed or reassigned in the dashboard.
PolicyPollIntervalSeconds	600	How often the agent fetches policy. The agent applies a one-time random offset after an immediate first poll so a fleet that updated together does not poll in lockstep. For urgent changes, use Check in now in the dashboard or Refresh policy in the tray.
NudgeRelayUrl	https://nudge.permitusb.com	Where the agent holds its single outbound connection for Check in now. Set to an empty string to disable the channel: the button then reports the endpoint as not connected and changes land on the regular schedule.
SyncIntervalSeconds	5	How often event batches are drained to the events endpoint.
MaxBatchSize	25	Cap on events per drain cycle.
WatchdogIntervalSeconds	30	Backstop poll for re-disabling a re-enabled device. A re-enable is normally caught in about a second by the device-change watcher; this is the safety net behind it.
MaxStalenessDays	7	How long the agent uses a cached policy before falling back to default-block when offline.

Editing the file

# 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": 600,
  "NudgeRelayUrl": "https://nudge.permitusb.com",
  "WatchdogIntervalSeconds": 30,
  "MaxStalenessDays": 7
}

Fleet deployment

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 and restarts the service
Ansible, Chef or Puppet: a standard copy or file resource onto the path, with a service-restart handler

Pulling a change without waiting for the next poll

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

What about the registry?

The MSI writes ApiUrl, EnrollmentToken and EndpointGroup under HKLM\Software\PermitUSB\Bootstrap 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, so editing those values post-enrollment has no effect. agent.json is canonical.

Something missing or wrong here? Tell us. Documentation gaps get filled fast.