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

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

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 status with 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:

Terminal
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

  1. Go to Settings > Agent Setup in the portal (or click Add devices on the Devices page) and open the macOS tab.

  2. Under Or install the PKG yourself, click Download PKG and copy the installer to the Mac.

  3. Install it.

    Either double-click the PKG and follow the installer, or run this in Terminal:

    Terminal
    sudo 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.

  4. Enroll the device with your token.

    Terminal
    sudo 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

Device naming templates are Windows-only. Macs always keep their existing hostname; you can assign a display name from the device detail page.

Verify the installation

  1. Check the enrollment status.

    Terminal
    sudo pckgr-agent status

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

  2. Check the daemon is loaded.

    Terminal
    sudo launchctl print system/com.pckgr.agent

    Look for state = running.

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

PathPurpose
/usr/local/pckgr/The agent binary
/usr/local/bin/pckgr-agentCLI symlink
/Library/Application Support/Pckgr/Device identity (root-only) and update cache
/Library/Logs/Pckgr/agent.logAgent operational log
/Library/LaunchDaemons/com.pckgr.agent.plistDaemon definition
/Library/LaunchAgents/com.pckgr.agent.remote.plistRemote desktop helper, run in the signed-in user’s session only during a session
~/Library/Logs/Pckgr/remote-helper.logThe remote desktop helper’s log, in the signed-in user’s home

Platform differences

Some Pckgr features are Windows-only today:

FeaturemacOS status
App deployment, assignments, deploymentsSupported (signed PKGs)
ScriptsSupported (Zsh / Bash)
Software inventorySupported
Agent auto-updateSupported
Remote desktopSupported after a one-time permission approval at the Mac
Remote shellSupported (zsh / bash, as root or the signed-in user)
Remote file managerWindows-only
Chat with the signed-in userWindows-only
Restart and shut down from the portalWindows-only
Self-Service PortalNot yet available
Custom fieldsWindows-only
Policies, Windows Update, vulnerability trackingWindows-only

Uninstall the agent

To remove the agent and all its data from a Mac:

Terminal
sudo pckgr-agent uninstall

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.

Manual removal

If the installed agent predates the uninstall command, remove it manually:

Terminal
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.agent

Troubleshooting

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

Terminal
sudo launchctl kickstart -k system/com.pckgr.agent

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

Terminal
sudo pckgr-agent reset
sudo pckgr-agent enroll --token "<your-token>"