Skip to main content
An MDM installs the agent with two pieces from the client’s Deployment tab: a configuration profile that carries the enrollment settings, and a signed package that installs the agent. You deploy both to the same Macs. The package enrolls the Mac with the key from the profile.
The MDM (profile + package) option appears on Deployment once the signed macOS package is available for your organization. Until then, install with the RMM script.
The requirements are the same as for the macOS agent: Apple Silicon Macs on macOS 12 or later. The package does not install on Intel Macs. The Macs must be enrolled in your MDM. Pre-approving the agent’s background items needs macOS 13 or later and user-approved MDM enrollment; without it, users see Background Items Added and can switch the agent off in Login Items.

​
Get the profile and the package

  1. Open the client and go to Deployment. Set the seat cap and create or paste an enrollment key.
  2. In the install step, pick macOS, then MDM (profile + package).
  3. Optional: tick Hide “Background Items Added” notifications. See what the profile contains before you do.
  4. Choose Download mspilot-agent-<client id>.mobileconfig. The button is off until the key field holds a valid key.
  5. Choose Copy package link, or download the package from the link under the buttons.
  6. Deploy the profile and the package with your MDM. The steps for each MDM are below.
  7. Back on Deployment, choose I’ve deployed them from my MDM.
Downloading the profile does not start the check-in watch. The watch starts when you choose I’ve deployed them from my MDM, and it runs for 30 minutes, because MDM delivery plus the agent’s retry can take 15 minutes or more. If it ends first, choose Watch again. If it times out, check /Library/Logs/MSPilot/install.log and /Library/Logs/MSPilot/enroll-retry.log on a Mac, then retry. The macOS choice is off when ImmyBot is the connected RMM (MSPilot’s ImmyBot installer is Windows only), so this method is not available there.

​
Use a dedicated enrollment key

Anyone signed in to a Mac can read the enrollment key from the installed profile. macOS writes it to /Library/Managed Preferences/io.mspilot.agent.plist, which every local user can read. Use a dedicated MDM enrollment key for this client and keep the client’s seat cap set.
Create a client key for the MDM and use it only there. Once the client is at its seat cap, machines that enroll with the key wait for approval instead of taking a seat. After rollout, revoke the key on Deployment. Enrolled Macs keep working, because they use their own device credential after enrolling, not the key. Your RMM scripts are untouched. A new Mac, or one that hits a rejected key, needs a valid key in the profile. To enroll more Macs later, create a new key and update the profile with it. In N-sight RMM, use Edit profile on the existing profile and choose to save and push the update. See Enrollment keys.

​
What the profile contains

The profile is built in your browser, with the key inside it. It is one system-scoped configuration profile named MSPilot agent. It is not signed. Your MDM signs it when you upload it.
The notification setting hides Background Items Added notifications for every app on those Macs, not only MSPilot. It applies to the next profile you download.
Apple accepts the Managed Login Items payload only on the device channel of a Mac whose MDM enrollment the user approved. Background items and their notifications are a macOS 13 feature. The profile’s identifier is the same for every file you download for a client, so a new download replaces the old profile when you deploy it.

​
The package

The package is mspilot-agent-macos.pkg, signed with a Developer ID Installer certificate and notarized by Apple. It installs the agent into /Library/Application Support/MSPilot and then runs the same install and enroll as the RMM script. It installs no app into /Applications. Deployment shows a versioned link:
Use that link as it is. Some MDMs, including N-sight RMM, refuse a download link that redirects. When Deployment cannot show a link, it says instead: “The macOS package is not published on this channel yet, or MSPilot could not confirm it just now. It ships with the next agent release; if a release already includes it, reload this page in a minute.” The package reports success to the MDM even while it waits for the profile. On each Mac, the package install logs to /Library/Logs/MSPilot/install.log and later enrollment retries to /Library/Logs/MSPilot/enroll-retry.log.

​
Deploy the profile first

Install the profile before the package when you can. The package then enrolls the Mac as soon as it installs. If the package lands first, the agent waits for the profile. install.log shows pending_profile waiting for the io.mspilot.agent configuration profile. The enroll retry job checks every 15 minutes, so the Mac enrolls within 15 minutes of the profile arriving. You do not reinstall the package.

​
Steps for your MDM

  1. In N-sight RMM, go to Dashboards → Device Management for Apple → Profiles → Upload profile. Enter a profile name and upload the .mobileconfig.
  2. On the Devices tab, select the Macs, choose Install profiles, select the MSPilot profile, and choose Install.
  3. In the All Devices view, select the same Macs, right-click, and choose Task → Add. Under Maintenance, pick the Automated Task Install Application from URL. For the frequency, choose Manual, then run it on demand once, so it does not reinstall the package on a schedule.
  4. Command Line: the versioned package link from Deployment.
  5. To change the key later, or after it was rejected, open the existing profile with Edit profile, upload the new file, and choose to save and push the update to the devices. Do not delete the profile and upload it again. That fails with A profile with the same ID already exists.

​
When the key is rejected

The agent writes these lines on the Mac:
  • managed_install_rejected in /Library/Logs/MSPilot/install.log when the first package install hits the rejection, or in /Library/Logs/MSPilot/enroll-retry.log when a later retry does.
  • managed_install_waiting_for_new_key in enroll-retry.log on the retries after that.
Together they mean the gateway rejected the key or gateway URL in the profile. The agent stops sending that key and waits for a new one. It keeps checking every 15 minutes. To recover:
  1. On Deployment, create a new key, or paste a valid one.
  2. Download the profile again.
  3. Replace the profile in your MDM and deploy the update to the Macs. In N-sight RMM, use Edit profile on the existing profile and choose to save and push the update.
The agent retries within 15 minutes. You do not reinstall the package. A key sent to the wrong region’s gateway is rejected the same way, because regions do not share a database. Download the profile from the client’s Deployment tab so GatewayURL matches your organization.

​
Removing the profile

Removing the profile does not uninstall the agent, and it does not disable the device. 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.
Last modified on September 28, 2026