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).
In short
- The installer the portal offers is for Apple Silicon Macs on macOS 12 (Monterey) or later.
- Enrollment tokens are shared with Windows: the same token works for both platforms.
- Run the one-line install command from Agent Setup, or install the PKG and run
sudo pckgr-agent enroll. The Mac appears on Devices within about 30 seconds. - Run
pckgr-agent statuswith sudo; without it, it always reports "not enrolled". - Some features are Windows-only today; see Platform differences.
Prerequisites
- macOS 12 (Monterey) or later on an Apple Silicon Mac. Intel Macs are not 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.
Create an enrollment token
Tokens are shared between Windows and macOS enrollment: the same token works for both platforms. See Create an enrollment token.
Install with one command (recommended)
Once you create a token, the macOS tab of Settings > Agent Setup shows this command with the token filled in. Click Copy and run it in Terminal on each Mac; it asks for your password for sudo:
curl -fsSL https://api.pckgr.com/install/macos.sh | sudo bash -s -- --token '<your-token>'It downloads the current agent PKG, checks its SHA-256 hash, installs it and enrolls the Mac. If anything fails (an expired token, your account's device limit, an Intel Mac) it stops with the reason. A Mac that is already enrolled keeps its enrollment; add --force to enroll it again.
From an MDM or a script that already runs as root, set PCKGR_ENROLLMENT_TOKEN instead of passing --token.
Install the PKG yourself
Go to Settings > Agent Setup in the portal (or click Add devices on the Devices page) and open the macOS tab.
Under Or install the PKG yourself, click Download PKG and copy the installer to the Mac.
Install it.
Either double-click the PKG and follow the installer, or run this in Terminal:
Terminalsudo installer -pkg pckgr-agent-<version>-osx-arm64.pkg -target /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.
Terminalsudo pckgr-agent enroll --token "<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.
Note
Verify the installation
Check the enrollment status.
Terminalsudo pckgr-agent statusThis displays the device ID, API URL, and enrollment timestamp. It requires sudo: the identity file is readable only by root, so without sudo this always reports "not enrolled".
Check the daemon is loaded.
Terminalsudo launchctl print system/com.pckgr.agentLook 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.
- Checks inAbout every 5 minutes when idle; more often while it has work in progress
- New deployments and scripts are picked up at the next check-in.
- Deploys apps
- Downloads the signed PKG, verifies its hash, and runs the macOS installer.
- Runs scripts
- Written in Zsh or Bash (see Scripts).
- Reports inventory
- Of installed applications from
/Applications. - Self-updates
- Automatically, when a new agent version is released.
- Detects sleep and wake
- And checks in within seconds of the lid opening.
- Remote desktop
- When an admin connects, starts a helper in the signed-in user's session to show the screen and take input. The first session needs a one-time permission approval at the Mac (see Remote Desktop).
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 |
/Library/LaunchAgents/com.pckgr.agent.remote.plist | Remote desktop helper, run in the signed-in user’s session only during a session |
~/Library/Logs/Pckgr/remote-helper.log | The remote desktop helper’s log, in the signed-in user’s home |
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 | Supported after a one-time permission approval at the Mac |
| Remote shell | Supported (zsh / bash, as root or the signed-in user) |
| Remote file manager | Windows-only |
| Chat with the signed-in user | Windows-only |
| Restart and shut down from the portal | Windows-only |
| Self-Service Portal | Not yet available |
| Custom fields | Windows-only |
| Policies, Windows Update, vulnerability tracking | Windows-only |
Uninstall the agent
To remove the agent and all its data from a Mac:
sudo pckgr-agent uninstallAdd --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.
Manual removal
If the installed agent predates the uninstall command, remove it manually:
sudo launchctl bootout system/com.pckgr.agent
sudo launchctl bootout "gui/$(stat -f %u /dev/console)/com.pckgr.agent.remote"
sudo rm -f /Library/LaunchDaemons/com.pckgr.agent.plist /Library/LaunchAgents/com.pckgr.agent.remote.plist /usr/local/bin/pckgr-agent
sudo rm -rf /usr/local/pckgr "/Library/Application Support/Pckgr" /Library/Logs/Pckgr
sudo pkgutil --forget com.pckgr.agentTroubleshooting
Device doesn't appear in the portal
- Check enrollment:
sudo pckgr-agent status(without sudo it always reports "not enrolled", because the identity file is readable only by root) - 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)
Restart the agent
sudo launchctl kickstart -k system/com.pckgr.agentReset the agent
To wipe the device identity and re-enroll without reinstalling, run these and confirm the reset when asked (add --force to reset to skip the prompt). Use any active enrollment token:
sudo pckgr-agent reset
sudo pckgr-agent enroll --token "<your-token>"