---
title: MDM on macOS
sidebar:
  label: macOS
description: Deploy the scanner to your Macs with a configuration profile and the pre-filled install script, from any MDM.
---

On macOS, your mobile device management (MDM) tool delivers two files. A **configuration profile** carries the enrollment token, and the pre-filled `install.sh` installs the scanner. Nobody has to sign in on the Mac.

:::info
The screenshots and menu paths use Jamf Pro as an example. Kandji, Mosyle, Intune, and any other MDM that can push a custom settings profile and run a shell script as root use the same configuration. Only the menu names differ: use the table below to find the matching option in yours.
:::

## Before you begin

- The **Admin** role in Surface, to create the enrollment token.
- Administrator access to your MDM.
- The Macs are enrolled in your MDM, checking in, and meet the [requirements](/surface/deploy/requirements).

## What to set up in your MDM

| Setting | Value | Where it is in Jamf Pro |
| --- | --- | --- |
| Profile type | Custom settings (`.plist` upload) | Configuration profile › **Application & Custom Settings** › **Upload** |
| Preference domain | `com.superalign.surface` | **Preference Domain** field |
| Installer script | `install.sh`, unchanged, Shell/Bash | Settings › Computer management › **Scripts** |
| Runs as | root | Policies run scripts as root by default |
| Run frequency | Once per Mac | **Execution Frequency: Once per computer** |
| When it runs | The Mac's next check-in | **Trigger: Recurring Check-in** |
| Target Macs | The same Macs for the profile and the script | **Scope** tab on both |

1. **Download the two files from the console**

    Open [console.superalign.ai](https://console.superalign.ai) and sign in with your work account using SSO, Google, or Microsoft. A new organization shows no assets or endpoints until the first Mac enrolls.

    ![The SuperAlign console sign-in page](/install-script/sign-in.png)

    Open **Downloads** and select the **Silent install** tab.

    Under **Enrollment tokens**, click **New token**. Name it, for example "Silent install", choose an expiry, and click **Create Token**. See [Enrollment tokens](/surface/settings/enrollment-tokens).

    ![The New enrollment token dialog with a name and an expiry](/mdm-macos/new-token.png)

    In the **MDM** section, choose your MDM under **MDM selection**. Click the download button beside **Copy** to save `com.superalign.surface.plist`.

    ![The Silent install tab with an active token, Jamf Pro selected, and the com.superalign.surface.plist preview](/mdm-macos/config-file.png)

    Still in the **MDM** section, scroll to **Installer** and download `install.sh`.

    You now have two files: `com.superalign.surface.plist`, pushed as the configuration profile in the next step, and `install.sh`, added as a script after that. Both already contain your enrollment token. Share them only with the people who manage your MDM.

2. **Push the configuration profile**

    Push the profile before the script. It keeps the token on the Mac, so it survives a package reinstall.

    Create a new macOS configuration profile named, for example, "Surface Enroll". Apply it at computer level and install it automatically.

    Add a custom settings payload. MDMs call it custom settings, custom preferences, or a preference file.

    Enter `com.superalign.surface` as the preference domain. The console shows it under the file preview.

    Upload `com.superalign.surface.plist` and save.

    Scope the profile to the Macs that should run Surface. Note which ones: the script goes to the same Macs.

    **Jamf Pro:** Computers › Configuration profiles › New. Set **Level: Computer Level** and **Distribution Method: Install automatically**. Then **Application & Custom Settings** › **Upload** › **Add**, and the **Scope** tab.

    ![Jamf Pro New macOS Configuration Profile, General payload, named Surface Enroll at Computer Level with Install automatically](/mdm-macos/jamf-profile-general.png)

    ![Jamf Pro custom settings payload with the com.superalign.surface preference domain and the uploaded plist](/mdm-macos/jamf-profile-plist.png)

    The profile holds these keys:

    | Key | Type | Required |
    | --- | --- | --- |
    | `EnrollmentToken` | String | Yes |
    | `UserEmail` | String | No |
    | `UserFullName` | String | No |

    ```xml
    <dict>
      <key>EnrollmentToken</key>
      <string>sae_xxxxxxxx.yyyyyyyyyyyyyyyy</string>
      <key>UserEmail</key>
      <string>$EMAIL</string>
      <key>UserFullName</key>
      <string>$FULLNAME</string>
    </dict>
    ```

    **Jamf Pro**

    Jamf substitutes `$EMAIL` and `$FULLNAME` per Mac.

    **Kandji**

    Add a custom profile with the plist above. Kandji substitutes `$EMAIL`.

    **Mosyle**

    Add a custom profile. Use `%email%` for the user email.

    **Intune**

    Add a preference file (`.plist`) with the domain `com.superalign.surface`.

3. **Add the installer script**

    Create a new macOS shell script named, for example, "Surface Enrollment Script". If your MDM asks for a language, choose **Shell/Bash**. Paste the whole of `install.sh` into the editor, or upload the file, and save.

    Do not edit the file. It already contains your enrollment token.

    **Jamf Pro:** Settings › Computer management › Scripts › New. Name it on the **General** tab, then paste it on the **Script** tab.

    ![Jamf Pro Surface Enrollment Script with Shell/Bash selected and install.sh pasted in](/mdm-macos/jamf-script.png)

4. **Run the script on the Macs**

    Set the script to run once on each Mac, as root, at its next check-in, on the same Macs as the profile. If your MDM offers to run the script as the signed-in user, turn that off.

    Some MDMs do this with a separate policy, as Jamf Pro does. Others set the schedule and the target Macs on the script itself.

    **Jamf Pro:** Computers › Policies › New. Name it "Surface Enrollment" and keep **Enabled** checked. Set **Trigger: Recurring Check-in** and **Execution Frequency: Once per computer**. In the **Scripts** payload, add the script with **Priority: After**. On the **Scope** tab, add the same computers as the profile. Save.

    ![Jamf Pro New Policy with Recurring Check-in ticked and Execution Frequency set to Once per computer](/mdm-macos/jamf-policy-trigger.png)

    ![Jamf Pro policy Scripts payload with Surface Enrollment Script at priority After](/mdm-macos/jamf-policy-script.png)

5. **Verify**

    Each Mac receives the profile and the script at its next check-in. No one needs to do anything on the Mac.

    On the Mac, macOS first confirms the profile was delivered, and the Surface icon appears in the menu bar. Next, an **App Background Activity** notice says Surface can run in the background. Click the icon: **Status** shows `waiting for daemon…` while the service starts, then `active` after the first scan. The account is signed in with no login prompt, because the token handled enrollment.

    ![The Surface menu bar menu, first showing Status waiting for daemon, then Status active](/install-script/tray-status.png)

    From a terminal on the Mac:

    ```bash
    defaults read /Library/Managed\ Preferences/com.superalign.surface
    sudo surface status
    ```

    In the console, **Insights** now shows the assets found, the endpoint count, and the assets at each risk level.

    ![The top of the Insights page showing asset, endpoint, session, and governed-asset counts](/mdm-macos/insights.png)

    **Endpoints** lists the Mac as **Active**, with its risk, Surface version, assets found, and last seen time.

    ![The Endpoints page listing endpoints with risk, status, assets found, version, and last seen time; hostnames blurred](/mdm-macos/endpoints.png)

## If a Mac does not appear

- Check the Mac has checked in with your MDM since you assigned the script.
- Check the Mac has both the configuration profile and the script.
- Check the enrollment token still shows as **Active** under **Downloads** in the console.

For log errors, see [Troubleshooting](/surface/scanner/troubleshooting).

## Deploy the package instead

You can assign the macOS `.pkg` from the **Downloads** page instead of the script. Keep the configuration profile, since the package does not carry the token. Your MDM runs:

```bash
sudo installer -pkg SuperAlign-surface-{version}-darwin-{arch}.pkg -target /
```

The package is signed and notarized, so macOS does not ask for permissions again after updates.

## Uninstall through MDM

The package bundles an uninstaller. Run it from a script in your MDM:

```bash
sudo /opt/surface/bin/uninstall.sh --force
```

It deregisters the endpoint from the console, removes the service and files, and deletes the managed profile's settings so a reinstall cannot reuse a revoked token.

## Next steps

- [Browser extension](/surface/deploy/silent-install/mdm/browser-extension) if you plan to record AI websites
- [Troubleshooting](/surface/scanner/troubleshooting) if an endpoint does not appear
- [Update and uninstall](/surface/scanner/update-and-uninstall) for upgrades through the same deployment
