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.

WindowsOwners, Admins and MSP Technicians manage Agent Setup; Read Only and MSP Read Only can view

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

If your devices run AppLocker, App Control for Business, Attack Surface Reduction rules or a restrictive PowerShell execution policy, read Hardened Environments before enrolling: it lists every path the agent runs from, which files are signed, and the rules to put in place.

Create an enrollment token

Before installing the agent, you need an enrollment token.

  1. Go to Settings > Agent Setup in the portal sidebar, or click Add devices on the Devices page.

  2. Click New Token.

  3. Configure the token with the settings below.

  4. Click Create Token.

  5. 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.

StatusMeaning
ActiveToken can be used for enrollment
ExpiredToken has passed its expiration date
ExhaustedToken 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:

Command prompt or PowerShell (Administrator)
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:

PowerShell (Administrator)
$env:PCKGR_ENROLLMENT_TOKEN = '<your-token>'
irm https://api.pckgr.com/install/windows.ps1 | iex

Note

The command needs Windows PowerShell 5.1 or later and full language mode. On devices where AppLocker or WDAC restricts PowerShell, and for Intune, use the MSI below.

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:

Install and enroll
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:

Install with a log file
msiexec /i pckgr-agent-<version>.msi /qn /l*v install.log ENROLLMENT_TOKEN="<your-token>"

Note

The installer shows the enrollment token in the log as asterisks. Older installers wrote it in plain text, so if you kept or shared a log from one, click Refresh token on that token’s row in Settings > Agent Setup to replace its value.

To skip automatic device renaming for this device (even if device naming is enabled on the tenant), see Skipping device rename:

Install without renaming
msiexec /i pckgr-agent-<version>.msi /qn ENROLLMENT_TOKEN="<your-token>" SKIP_RENAME=1

Interactive install

  1. Double-click the MSI installer.

  2. Follow the installation wizard.

  3. When prompted, paste your enrollment token.

  4. Optionally check Skip automatic device renaming.

    Do this if you don't want this device to be renamed.
  5. Complete the wizard.

    The agent service starts automatically.

Deploy with Group Policy or SCCM

You can distribute the MSI through your existing deployment tools.

  1. Place the MSI on a network share accessible to target devices.

  2. Configure the MSI property ENROLLMENT_TOKEN=<your-token>.

  3. Optionally add SKIP_RENAME=1 to prevent automatic device renaming.

  4. 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:

Enroll
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" enroll --token <your-token>

To skip automatic device renaming:

Enroll without renaming
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" enroll --token <your-token> --skip-rename

In 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.

MethodHow to skip
One-line installAdd -SkipRename after the token
Interactive installCheck Skip automatic device renaming on the enrollment dialog
Silent installAdd SKIP_RENAME=1 to the msiexec command
CLI enrollmentAdd --skip-rename to the enroll command
Group Policy / SCCMAdd 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.

  1. Check the service.

    Command prompt
    sc query PckgrAgent

    The service should show STATE: RUNNING.

  2. Check the enrollment status in an elevated Command Prompt.

    Command prompt (Administrator)
    "C:\Program Files\Pckgr\Agent\pckgr-agent.exe" status

    This 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.

  3. 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.

StatusMeaning
OnlineChecked in within the last 7 minutes
AwayChecked in 7–30 minutes ago
OfflineChecked in more than 30 minutes ago
DormantNo check-in for longer than the dormant threshold (default: 30 days)

Data storage

The agent stores its data in C:\ProgramData\Pckgr\:

FolderPurpose
device.jsonEncrypted 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

Uninstall
msiexec /x pckgr-agent-<version>.msi /qn

Use 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:

Command prompt (Administrator)
"C:\Program Files\Pckgr\Agent\pckgr-agent.exe" reset

Reset removes the device identity

The command asks you to confirm (type 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.