Installing the Agent
The Pckgr agent is a Windows service that runs on each managed device. It handles application deployments, script execution, policy enforcement, and status reporting. For Mac devices, see Installing the Agent on macOS.
In short
- Create an enrollment token under Settings > Agent Setup, then run the one-line install command it shows.
- The full token is shown only when you create or refresh it. Copy it straight away.
- The command downloads, checks, installs and enrolls in one go; the device appears on Devices within a minute. The MSI is still there for Intune and other deployment tools.
- The agent checks in about every 5 minutes when idle, so new deployments and scripts start at the next check-in.
Prerequisites
- Windows 10 or Windows 11
- Administrator access on the device
- Network access to the Pckgr API
- An enrollment token (generated from the portal)
Locked-down devices
Create an enrollment token
Before installing the agent, you need an enrollment token.
Go to Settings > Agent Setup in the portal sidebar, or click Add devices on the Devices page.
Click New Token.
Configure the token with the settings below.
Click Create Token.
Copy the token value.
The full token is shown only when you create or refresh it, and it can't be viewed again after you leave the page.
- Expires In1–365 days, default 7
- How many days until the token expires.
- Never expires
- Turn this on instead of setting days when the token will be baked into an Intune or other MDM deployment that keeps enrolling devices for months. The token stays valid until you delete it, so give it a sensible use limit and delete it once the rollout is done.
- Maximum Uses1–10,000, default 100
- How many devices can enroll with this token.
Manage tokens
The Agent Setup page shows all your enrollment tokens with their status.
| Status | Meaning |
|---|---|
| Active | Token can be used for enrollment |
| Expired | Token has passed its expiration date |
| Exhausted | Token has reached its maximum use count |
If you've lost a token's value, click Refresh token on its row. This issues a new value and shows it so you can copy it; the old value stops working straight away, while the token keeps its expiry date and use count.
You can delete tokens you no longer need. Deleting a token is also how you revoke a never-expiring one. Deleting a token does not affect devices that have already enrolled with it.
Install with one command (recommended)
Once you create a token, the Windows tab of Settings > Agent Setup shows this command with the token filled in. Click Copy and run it in an elevated command prompt or PowerShell on each device:
powershell -c "& ([scriptblock]::Create((irm https://api.pckgr.com/install/windows.ps1))) -Token '<your-token>'"It downloads the current agent installer, checks its SHA-256 hash, installs it silently and enrolls the device, then says whether enrollment worked. If anything fails (an expired token, your account's device limit) it stops with the reason and exits with code 1. Add -SkipRename to keep the device's name; see Skipping device rename.
Running it again is safe. On a device that is already enrolled with the current agent it changes nothing, on one with an older agent it updates the agent and keeps the enrollment, and on one whose agent program or service is missing it repairs the agent and keeps the enrollment. To move a device to another tenant, uninstall the agent first.
From an RMM tool or script
Tools that pass values as environment variables can set PCKGR_ENROLLMENT_TOKEN and run the script directly:
$env:PCKGR_ENROLLMENT_TOKEN = '<your-token>'
irm https://api.pckgr.com/install/windows.ps1 | iexNote
Silent install with the MSI
Download the installer from Settings > Agent Setup with Download MSI. The file is named pckgr-agent-<version>.msi, where <version> is the current agent version; use the real file name in the commands below. The Agent Setup page shows the install command under Or install the MSI yourself, with the file name already filled in.
Run this command in an elevated command prompt or PowerShell:
msiexec /i pckgr-agent-<version>.msi /qn ENROLLMENT_TOKEN="<your-token>"This installs the agent silently and enrolls the device in one step. The agent starts automatically as a Windows service.
To include a log file for troubleshooting:
msiexec /i pckgr-agent-<version>.msi /qn /l*v install.log ENROLLMENT_TOKEN="<your-token>"Note
To skip automatic device renaming for this device (even if device naming is enabled on the tenant), see Skipping device rename:
msiexec /i pckgr-agent-<version>.msi /qn ENROLLMENT_TOKEN="<your-token>" SKIP_RENAME=1Interactive install
Double-click the MSI installer.
Follow the installation wizard.
When prompted, paste your enrollment token.
Optionally check Skip automatic device renaming.
Do this if you don't want this device to be renamed.Complete the wizard.
The agent service starts automatically.
Deploy with Group Policy or SCCM
You can distribute the MSI through your existing deployment tools.
Place the MSI on a network share accessible to target devices.
Configure the MSI property
ENROLLMENT_TOKEN=<your-token>.Optionally add
SKIP_RENAME=1to prevent automatic device renaming.Deploy as a standard MSI package.
The API URL is built into the MSI at build time, so you don't need to specify it separately.
Enroll from the command line
If you installed the agent without an enrollment token, you can enroll manually. The agent is installed in C:\Program Files\Pckgr\Agent\ and is not on the system PATH, so use its full path. In an elevated Command Prompt, run:
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" enroll --token <your-token>To skip automatic device renaming:
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" enroll --token <your-token> --skip-renameIn PowerShell, put & and a space in front of the quoted path.
Skipping device rename
When device naming is enabled on a tenant, every newly enrolled device is automatically renamed using the configured template. If you want to enroll a specific device without renaming it (e.g., servers, kiosks, or machines that already have a correct name), you can opt out on a per-device basis.
| Method | How to skip |
|---|---|
| One-line install | Add -SkipRename after the token |
| Interactive install | Check Skip automatic device renaming on the enrollment dialog |
| Silent install | Add SKIP_RENAME=1 to the msiexec command |
| CLI enrollment | Add --skip-rename to the enroll command |
| Group Policy / SCCM | Add SKIP_RENAME=1 to the MSI properties |
This is a per-device decision made at enrollment time. It does not change the tenant-level setting: other devices will continue to be renamed as normal. If you later want to rename a device that was enrolled with skip rename, you can assign a name manually from the device detail page in the portal.
Verify the installation
After installation, verify the agent is running.
Check the service.
Command promptsc query PckgrAgentThe service should show
STATE: RUNNING.Check the enrollment status in an elevated Command Prompt.
Command prompt (Administrator)"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" statusThis displays the device ID, the API URL, the enrollment timestamp, the identity file location, and the work directory path with the number of job folders in it.
Check the portal.
The device should appear on the Devices page within a minute of enrollment.
How the agent works
Once installed, the agent runs continuously in the background.
- Checks inAbout every 5 minutes when idle; every 15–30 seconds while it has work in progress
- New deployments and scripts are picked up at the next check-in. Check in, Restart and Shut down on a device, and starting a remote session, reach a connected Windows device within seconds.
- Checks appsWhen something about an app changed, and otherwise about once an hour
- An assigned app’s detection check runs when the app or its detection rule changes, after one of its installs or uninstalls, while it is waiting to be installed, and otherwise about once an hour. Check in on a device checks every assigned app straight away.
- Executes deployments
- Downloads application packages, runs the installer, and reports results.
- Reports status
- Including connection health, Windows Update information, and installed software inventory.
- Enforces policies
- Applies configuration settings and reports compliance.
- Uploads logs
- After each job, for review in the portal.
Connection status
The portal shows each device's connection status based on how recently it checked in.
| Status | Meaning |
|---|---|
| Online | Checked in within the last 7 minutes |
| Away | Checked in 7–30 minutes ago |
| Offline | Checked in more than 30 minutes ago |
| Dormant | No check-in for longer than the dormant threshold (default: 30 days) |
Data storage
The agent stores its data in C:\ProgramData\Pckgr\:
| Folder | Purpose |
|---|---|
device.json | Encrypted device identity (DPAPI-protected) |
Logs\ | Agent operational logs (rotates at 10 MB) |
Cache\ | Cached policy assignments |
Work\ | One folder per job: the downloaded package, its extracted contents and the job’s output (deleted when the job finishes) |
Scripts\ | Detection scripts for User-context apps, written before each run and deleted after it |
Branding\ | Your organization’s logo, shown in app install prompts |
Uninstall the agent
msiexec /x pckgr-agent-<version>.msi /qnUse the MSI for the version that is installed. You can also uninstall Pckgr Agent from Settings > Apps > Installed apps in Windows.
This stops the service and removes the agent's own data from C:\ProgramData\Pckgr: the device identity (device.json), Work\, Cache\, Scripts\ and Branding\.
Logs\ is kept so the agent and update logs remain available for troubleshooting, and files that belong to other Pckgr products in that folder are never touched. The folder itself is removed only if it is empty afterwards.
To remove the device from the portal, delete it from the Devices page.
Troubleshooting
Device doesn't appear in the portal
- Verify the service is running:
sc query PckgrAgent - Check the enrollment status:
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" status - If your account has reached its device limit, enrollment is refused. See Device Usage.
- Review the agent log at
C:\ProgramData\Pckgr\Logs\agent.log - Ensure the device has network access to the Pckgr API
- Verify the enrollment token is still active and not expired or exhausted
Jobs are not executing
- Confirm the service is running:
sc query PckgrAgent - Check agent logs for errors:
C:\ProgramData\Pckgr\Logs\agent.log - Verify the device is in a group that has app assignments
Agent service won't start
- Check Windows Event Viewer under Windows Logs > Application for entries from the source Pckgr Agent
- Ensure no other instance is running
- The service automatically restarts on failure (with a 60-second delay)
Reset the agent
If you need to start fresh, run this in an elevated Command Prompt:
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" resetReset removes the device identity
y). It deletes the device identity and the agent's work data (Work\, Cache\, Scripts\ and Branding\). Logs\ is kept for troubleshooting. Afterwards, enroll the device again with an active token.