Skip to main content
The macOS agent enrolls a Mac with the gateway and writes the settings for the apps on each signed-in user. You install it with a script from your RMM, from Terminal on one Mac, or with a package and profile from an MDM.

​
Requirements

  • An Apple Silicon Mac. The script refuses an Intel Mac with refused: Apple Silicon (arm64) required, and the package will not install on one.
  • macOS 12 (Monterey) or later, for every install method: RMM script, Terminal, and MDM. The script does not check the version, but older versions are not tested or supported.
  • For an MDM that pre-approves the agent’s background items: macOS 13 or later and user-approved MDM enrollment. See macOS MDM.
  • Root. RMM scripts run as root (the System context in most RMMs). Nobody needs to be signed in for the install or the enroll.
Deployment does not install apps on macOS yet. When you tick apps under AI applications and pick macOS, Deployment says the script installs and enrolls the MSPilot agent only.

​
Install

Open the client and go to Deployment. Under Install the MSPilot agent, set the seat cap and create or reuse an enrollment key. In the install step, pick macOS. The enrollment key, the gateway URL, and the channel are already inside the script you copy. Leave the RMM’s script variables or parameters empty. Deployment lists the exact fields for your RMM, and each RMM page repeats them: NinjaOne, Datto, ConnectWise RMM, Level, Syncro, N-sight RMM. MSPilot’s ImmyBot installer is Windows only. When ImmyBot is the connected RMM, the macOS choice on Deployment is turned off and shows MSPilot’s ImmyBot installer is Windows only. Give the job at least 600 seconds (10 minutes) so the agent can download. Enroll refuses to run as a signed-in user. If the RMM runs the script as the user, it prints refused: enroll must run as root (set the RMM script to run as System) and exits 2. You do not schedule a pull job on macOS. You can schedule the same script daily if you like. Running it again is a safe repair: it brings the binary up to date and registers the jobs again. After you choose I’ve run it in plus your RMM’s name (for example I’ve run it in NinjaOne), Deployment watches this client for check-in for 10 minutes. If it times out, check the RMM job output against the exit codes, then choose Watch again.

​
One Mac without an RMM

Installer links and emails are Windows only. On a Mac, download the script and run it in Terminal.
  1. Choose Download mspilot-enroll.sh. macOS saves it to your Downloads folder.
  2. Open Terminal: Finder → Applications → Utilities → Terminal.
  3. Run the file, then type the Mac’s administrator password:
Keep Terminal open until the script finishes, then choose I ran the installer. Deployment watches for the Mac to check in. If it times out, check the script’s output in Terminal on the Mac, then retry.

​
What gets installed

The script downloads the agent from https://downloads.mspilot.io/agent/<channel>/ and checks it against that channel’s SHA256SUMS before it runs it. The default channel is latest.

​
Scheduled jobs

The pull and update jobs wait a random delay of up to 5 minutes before they run, so a fleet does not call the gateway at the same second.

​
Per-user configuration

The enroll runs as root and saves the device state. The signed-in user’s AI apps are configured right away; other users at their next sign-in, then hourly. There is no RMM step per user. On an RMM install, macOS 13 and later can show Background Items Added for the agent’s jobs, and a user can switch them off in System Settings → General → Login Items. The MDM profile pre-approves the jobs so users cannot switch them off. That needs macOS 13 or later and user-approved MDM enrollment.

​
Self-update

The update job runs every day at 03:00, plus the random delay. It compares the installed agent with the channel’s SHA256SUMS and replaces it when they differ. A successful update writes agent_updated to /Library/Logs/MSPilot/update.log. Running the install script again also brings the agent up to date.

​
Logs

An RMM run writes its output to the RMM job, not to a file. The per-user pull job does not keep a log. To check a Mac by hand, run this as the signed-in user:

​
Script exit codes

Later retries and daily updates log to /Library/Logs/MSPilot/enroll-retry.log and /Library/Logs/MSPilot/update.log. The agent’s own exit 4, pending, never reaches the RMM. The script turns it into exit 0 and prints mspilot_pending.

​
Troubleshooting

/Users/Shared is writable by every user. Before the agent keeps state there, the script checks that /Users/Shared/MSPilot is a real folder owned by root. When it finds a symlink, a file, or a folder a user owns, it moves it aside into /Users/Shared/.MSPilot.stale.<random> and creates a fresh folder. Exit 5 means the script could not move it aside (refused: cannot move aside), could not create the fresh folder (refused: cannot create), or found that the folder changed while it was setting it up (changed during setup). The agent does not run after a refusal.Run the script again. If it repeats, check what is at /Users/Shared/MSPilot: sign in as an administrator and run ls -ldO /Users/Shared/MSPilot, which shows the owner and any file flags. Rename or remove what is there, then run the script again.On an MDM install, install.log shows mspilot_pkg_postinstall_exit rc=5 and mspilot_pkg_postinstall_no_fallback reason=bootstrap_refused. No retry job is set up after a refusal, so fix the folder, then deploy the package again from the MDM.
The gateway accepted the key and queued the Mac. It is waiting for approval at the seat cap, or for the RMM to report the Mac. The job still exits 0.Approve the Mac on the client’s Devices tab, or raise Seat cap on Deployment. See the FAQ. You do not run the script again. The enroll retry job tries every 15 minutes and finishes the enroll once the Mac is approved or reported. It then removes itself.
The RMM ran the script as the signed-in user. Set the script to run as root. NinjaOne and Syncro call this System, and Level calls it Local system. Then run it again.
enroll_error wrong_region means the key belongs to a different gateway region. enroll_error invalid_enrollment_key means the gateway does not accept the key: it is revoked or mistyped, or it was sent to another region’s gateway. Regions do not share a database, so another region cannot look the key up.Copy the script again from the client’s Deployment tab. That copy carries your organization’s gateway URL and a live key. Do not edit the gateway URL by hand.When the gateway could not be reached, enroll_error is followed by the network error instead of a reason code. Run the script again once the Mac can reach the gateway.
The Mac has an Intel processor. MSPilot supports Apple Silicon Macs only.
To take a Mac’s seat back, open the client’s Devices tab and choose Disable on that row. There is no macOS unenroll or uninstall script in Admin; the scripts under Maintenance scripts are Windows PowerShell only.
Last modified on September 28, 2026