Installing the Agent on macOS
The Pckgr macOS agent is a background daemon that runs on each managed Mac. It handles application deployments (signed PKG installers), shell script execution, software inventory, and status reporting.
For Windows devices, see Installing the Agent (Windows).
Prerequisites
- macOS 12 (Monterey) or later - Apple Silicon and Intel are both supported
- Administrator (sudo) access on the Mac
- Network access to the Pckgr API
- An enrollment token (generated from the portal)
The installer is signed with a Developer ID certificate and notarized by Apple, so Gatekeeper accepts it without warnings.
Generating an Enrollment Token
Tokens are shared between Windows and macOS enrollment - the same token works for both platforms. See Generating an Enrollment Token.
Installation
- Go to Settings > Agent Setup in the portal and open the macOS tab.
- Click Download PKG and copy the installer to the Mac.
- Install it - double-click the PKG, or from Terminal:
The PKG filename includes the agent version, so use the exact name of the file you downloaded. The Agent Setup page shows the command with the version already filled in.
- Enroll the device with your token:
The daemon is already running after installation (it waits for enrollment), so within about 30 seconds of enrolling, the Mac checks in and appears on the Devices page.
Device naming templates are Windows-only - Macs always keep their existing hostname. You can assign a display name from the device detail page.
Verifying the Installation
Check enrollment status
Requires sudo - the identity file is readable only by root, so without sudo this always reports "not enrolled".
Check the daemon is loaded
Look for state = running.
Check the portal
The device should appear on the Devices page within a minute of enrollment.
How the Agent Works
Once enrolled, the agent runs continuously as a launchd daemon:
- Polls for jobs to check for new deployments or scripts
- Deploys apps by downloading the signed PKG, verifying its hash, and running the macOS installer
- Runs scripts written in Zsh or Bash
- Reports inventory of installed applications
- Self-updates automatically when a new agent version is released
- Detects sleep/wake and checks in within seconds of the lid opening
Data Storage
| Path | Purpose |
|---|---|
| /usr/local/pckgr/ | The agent binary |
| /usr/local/bin/pckgr-agent | CLI symlink |
| /Library/Application Support/Pckgr/ | Device identity (root-only) and update cache |
| /Library/Logs/Pckgr/agent.log | Agent operational log |
| /Library/LaunchDaemons/com.pckgr.agent.plist | Daemon definition |
Platform Differences
Some Pckgr features are Windows-only today:
| Feature | macOS status |
|---|---|
| App deployment, assignments, deployments | Supported (signed PKGs) |
| Scripts | Supported (Zsh / Bash) |
| Software inventory | Supported |
| Agent auto-update | Supported |
| Remote desktop | Not yet available |
| Self-Service Portal | Not yet available |
| Policies, Windows Update, vulnerability tracking | Windows-only |
Uninstalling the Agent
To remove the agent and all its data from a Mac:
Add --force to skip the confirmation prompt. This stops the daemon and removes the binary, device identity, logs, and installer receipt. To finish offboarding, delete the device from the Devices page in the portal.
Troubleshooting
Device doesn't appear in the portal
- Check enrollment:
sudo pckgr-agent status - Review the agent log at
/Library/Logs/Pckgr/agent.log - Ensure the Mac 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 daemon is running:
sudo launchctl print system/com.pckgr.agent - Check the agent log for errors
- Verify the device is in a group that has app assignments (macOS apps only deploy to macOS devices)
Restarting or resetting the agent
- Restart:
sudo launchctl kickstart -k system/com.pckgr.agent - Re-enroll without reinstalling:
sudo pckgr-agent resetthensudo pckgr-agent enroll --token "<new-token>"