> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mspilot.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> MSPilot enrolls technician Windows machines and Apple Silicon Macs so Claude Desktop and ChatGPT run through one governed gateway. Seat words are standard seat and power seat. ConnectWise PSA import is not available. HIPAA is not a self-serve switch.

# macOS MDM

> Install the agent on Apple Silicon Macs with a configuration profile and a signed package from your MDM.

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.

<Note>
  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](/agent/macos).
</Note>

The requirements are the same as for the [macOS agent](/agent/macos): 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](#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](#steps-for-your-mdm).
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

<Warning>
  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.
</Warning>

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](#when-the-key-is-rejected), 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](/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.

| Payload                                 | What it does                                                                                                                                                                                        |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MSPilot agent settings**              | Managed preferences in the `io.mspilot.agent` domain: `EnrollmentKey`, `GatewayURL`, and `Channel`. `Channel` is left out when it is `latest`.                                                      |
| **MSPilot background items**            | A Managed Login Items rule that approves every background item signed with the agent's Apple Team ID. macOS treats the agent's jobs as managed, so users cannot switch them off in **Login Items**. |
| **Hide Background Items notifications** | Only when you tick the box. It turns off macOS's **Background Items Added** notifications.                                                                                                          |

<Warning>
  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.
</Warning>

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:

```text theme={"system"}
https://downloads.mspilot.io/agent/<version>/mspilot-agent-macos.pkg
```

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

<Tabs>
  <Tab title="N-sight">
    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`.
  </Tab>

  <Tab title="Intune">
    1. Go to **Devices → Manage devices → Configuration → Create → New policy**. Set **Platform** to **macOS** and **Profile type** to **Templates → Custom**.
    2. Set **Deployment channel** to **Device channel**. Intune does not let you change the channel after you save. Upload the `.mobileconfig` and assign it to the Macs.
    3. Go to **Apps → All Apps → Create**. Set **Platform** to **macOS** and the app type to **macOS app (PKG)**. Upload the package and assign it as **Required** to the same Macs.

    You can add the package as a **Line-of-business app** instead. Intune requires a Developer ID Installer signature for that type, and this package has one. The package installs no app, so Intune may not report success for it.
  </Tab>

  <Tab title="Jamf Pro">
    1. Go to **Computers → Configuration Profiles** and upload the `.mobileconfig`. Scope the profile to the Macs.
    2. Go to **Settings → Computer management → Packages → New** and upload the package.
    3. Go to **Computers → Policies → New**. In the **General** payload, set the triggers **Enrollment Complete** and **Recurring Check-in**, and the execution frequency **Once per computer**. In the **Packages** payload, add the package with the **Install** action. Scope the policy to the same Macs.
  </Tab>

  <Tab title="Kandji">
    1. Go to **Library → Add Library Item → Custom Profile**. Upload the `.mobileconfig` and assign it to the Macs' Blueprint.
    2. Go to **Library → Add Library Item → Custom App**. Upload the package as an **Installer Package** and assign it to the same Blueprint.
  </Tab>

  <Tab title="Mosyle">
    These steps follow the labels **Deployment** shows. Menu names can differ in your Mosyle console.

    1. Under **Management → Certificates/Custom Profiles**, upload the `.mobileconfig` and assign it to the Macs.
    2. Under **Management → Install PKG**, add the package and assign it to the same Macs.
  </Tab>
</Tabs>

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