Deploy the Orb sensor on macOS using Microsoft Intune

This guide walks you through deploying the Orb sensor to a macOS fleet using Microsoft Intune. The guide covers:

1. What the sensor package installs, and how it differs from the Orb app
2. Delivering your Deployment Token with a configuration profile
3. Allowing the sensor's background item so it starts at login
4. Adding the package as a macOS PKG app, and assigning it
5. Verifying, controlling updates, and uninstalling
6. The files and processes to allow-list in endpoint security tools

Requirements:

1. An Orb Cloud subscription that includes Deployment Tokens (all paid plans)
2. Microsoft Intune, and administrative access to the Microsoft Intune admin center
3. macOS 11.0 or later, enrolled in Intune, with the Intune macOS agent installed
4. A Deployment Token for your Space

Orb sensor package

The sensor ships as a flat, signed installer package, which always points to the latest stable release:

https://pkgs.orb.net/stable/macos/orb-sensor.pkg

To verify the download, compare its SHA-256 with the checksum published beside that release. orb-sensor-version.txt holds the current version number:

curl -fsSLO https://pkgs.orb.net/stable/macos/orb-sensor.pkg
VERSION="$(curl -fsSL https://pkgs.orb.net/stable/macos/orb-sensor-version.txt)"
curl -fsSL "https://pkgs.orb.net/stable/macos/orb-sensor-$VERSION.pkg.sha256"
shasum -a 256 orb-sensor.pkg

The two hashes must match.

Deploy the configuration profile first

The sensor reads its managed settings from /Library/Managed Preferences/net.orb.orb.plist, which macOS writes when a configuration profile containing a net.orb.orb payload is installed.

Create and assign the configuration profile before the app, to the same group.

Intune does not guarantee the order in which a profile and an app reach a device, so this is not a hard guarantee — but in practice a configuration profile applies well before a PKG app, because the app cannot install until the Intune management agent is itself installed. Getting the profile in place first makes the race moot.

The order matters twice. The installer reads SensorOnboarding only while the package installs, so a profile that arrives afterwards cannot delay that Mac's introduction. And the sensor reads the token only when it starts.

If a sensor does start before its token arrives, it runs unlinked and the Mac does not appear in your Space. Once the profile lands, restart the agent to pick it up:

launchctl kickstart -k "gui/$(id -u)/net.orb.sensor"

Create a Deployment Token

1. Visit https://cloud.orb.net/orchestration
2. Select Create new token
3. Enter a name and select Create
4. Keep this page open for the next step

Use a dedicated, revocable token per deployment so you can attribute devices and revoke access without disrupting other rollouts.

Create the .mobileconfig

Create a file named orb-sensor.mobileconfig with the following contents. This is the recommended baseline for a managed deployment. It does three things:

• links the Orb to your Space
• keeps the sensor off mDNS
• names each Mac after its Intune device name and serial number
• delays the first-run introduction until the user next logs in, so no window appears on screen while someone is working

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>net.orb.orb</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>net.orb.orb.deployment</string>
            <key>PayloadUUID</key>
            <string>REPLACE-WITH-UUID-1</string>
            <key>PayloadDisplayName</key>
            <string>Orb Deployment Configuration</string>
            <key>PayloadOrganization</key>
            <string>Your Organization</string>
            <key>OrbDeploymentToken</key>
            <string>REPLACE-WITH-YOUR-DEPLOYMENT-TOKEN</string>
            <key>OrbEnvironment</key>
            <dict>
                <key>ORB_ZEROCONF_PUBLISH</key>
                <string>false</string>
                <key>ORB_ZEROCONF_BROWSE</key>
                <string>false</string>
                <key>ORB_DEVICE_NAME_OVERRIDE</key>
                <string>{{devicename}}-{{serialnumber}}</string>
            </dict>
            <key>SensorOnboarding</key>
            <string>next-login</string>
        </dict>
    </array>
    <key>PayloadDisplayName</key>
    <string>Orb Sensor Configuration</string>
    <key>PayloadIdentifier</key>
    <string>net.orb.orb.configuration</string>
    <key>PayloadOrganization</key>
    <string>Your Organization</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>REPLACE-WITH-UUID-2</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadScope</key>
    <string>System</string>
</dict>
</plist>

Replace the placeholders:

1. Generate two UUIDs. On macOS, run uuidgen twice in Terminal, or uuidgen | pbcopy to copy one at a time.
2. Substitute them for REPLACE-WITH-UUID-1 and REPLACE-WITH-UUID-2.
3. Substitute your Deployment Token for REPLACE-WITH-YOUR-DEPLOYMENT-TOKEN.

Why each setting is as it is:

Setting	Why
OrbDeploymentToken	Links the Orb to your Space without any user action.
OrbEnvironment → ORB_ZEROCONF_PUBLISH "false"	Stops the sensor advertising itself over mDNS, which most managed fleets do not want.
OrbEnvironment → ORB_ZEROCONF_BROWSE "false"	Stops the sensor discovering other Orbs over mDNS. The sensor does not browse by default; setting it keeps the profile explicit.
OrbEnvironment → ORB_DEVICE_NAME_OVERRIDE "{{devicename}}-{{serialnumber}}"	Names the Orb after the Mac's Intune device name and serial number, for example frontdesk-mac-C02XK1ABCDEF, so it is easy to match to the device in Intune. Intune fills in the variables for each Mac. See Name each Mac.
SensorOnboarding next-login	The sensor starts monitoring as soon as the package installs, but the introduction and its Location request wait until the user next logs in.

The profile leaves OrbSkipIntroduction unset on purpose. The introduction is where users grant Location, and without Location you lose SSID and BSSID. See Keep the introduction.

Set environment variables with OrbEnvironment

OrbEnvironment is a dictionary. Each key is the name of an Orb environment variable, and the sensor applies it at startup as if it had been set in the sensor's environment. Any variable listed in Configuration can be set this way.

For example, to also turn off first-hop measurement, add ORB_FIRSTHOP_DISABLED beside the variables already in the profile:

<key>OrbEnvironment</key>
<dict>
    <key>ORB_ZEROCONF_PUBLISH</key>
    <string>false</string>
    <key>ORB_ZEROCONF_BROWSE</key>
    <string>false</string>
    <key>ORB_DEVICE_NAME_OVERRIDE</key>
    <string>{{devicename}}-{{serialnumber}}</string>
    <key>ORB_FIRSTHOP_DISABLED</key>
    <string>1</string>
</dict>

Rules:

• Every value must be a <string>, including booleans and numbers: <string>false</string>, <string>1</string>, never <false/> or <integer>1</integer>.
• Names must start with ORB_ and contain only uppercase letters, digits and underscores.

The sensor reads these settings when it starts. After you change the profile, the change takes effect when the sensor next starts, for example at the user's next login. To apply it sooner, restart the agent:

launchctl kickstart -k "gui/$(id -u)/net.orb.sensor"

The sensor logs Using environment setting from MDM configuration for each variable it applies. The log line includes the variable name but never its value, so tokens do not end up in logs.

If OrbEnvironment contains ORB_DEPLOYMENT_TOKEN, that value takes precedence over OrbDeploymentToken. Use one or the other. A setting pushed from Remote Configuration can block local overrides, and that includes these.

Name each Mac

By default the sensor reports the Mac's hostname. To report a different name, set ORB_DEVICE_NAME_OVERRIDE in OrbEnvironment.

One profile is usually assigned to many Macs, so do not use a fixed name: every Mac in the group would appear with the same name. Use Intune's device variables instead. Intune replaces them with each Mac's own values before it delivers the profile:

Value	Reports as
{{devicename}}-{{serialnumber}}	frontdesk-mac-C02XK1ABCDEF
{{serialnumber}}	C02XK1ABCDEF
{{devicename}}	frontdesk-mac

Variables are case-sensitive, and Intune does not check them when you upload the profile. A misspelled variable, such as {{DeviceName}}, reaches the Mac as literal text. To confirm Intune substituted the values, check the managed preferences on a Mac:

plutil -extract OrbEnvironment.ORB_DEVICE_NAME_OVERRIDE raw "/Library/Managed Preferences/net.orb.orb.plist"

This command should print the Mac's own values, not the text in braces. For other variables, see Microsoft's list of supported tokens.

The sensor reads the name when it starts. A Mac that is already reporting picks up a new name the next time its sensor starts. A package upgrade also restarts the sensor, and so does the launchctl kickstart command above.

Supported keys

Key	Type	Effect
OrbDeploymentToken	String	Links the Orb to your Space. Required for unattended deployment.
OrbEnvironment	Dictionary of strings	Sets any Orb environment variable. See above.
SensorOnboarding	String	immediate (default) or next-login. With next-login, the introduction and Location request wait until the next login. The sensor starts monitoring immediately either way. Read only by the installer, at installation or upgrade.
OrbAllowIntroductionLater	Boolean	Adds a Later button to the introduction. It closes the introduction without requesting Location, and the introduction appears again at the next login. Defaults to false.
OrbSkipIntroduction	Boolean	Suppresses the introduction screen and immediately prompts for permissions.
OrbEnableRestrictions	Boolean	Skips the introduction and stops the sensor requesting permissions. It also keeps mDNS discovery off. Defaults to false.
OrbEnableLocationPrompt	Boolean	With OrbEnableRestrictions, allows the Location request again. Ignored without restrictions.
OrbEnableNetworkPrompt	Boolean	With OrbEnableRestrictions, allows mDNS discovery and direct DNS lookups. These can trigger a Local Network prompt. Ignored without restrictions.
OrbAutoUpdateEnabled	Boolean	false stops the sensor's own updater. Defaults to true. See Control updates.

Keep the introduction

Do not suppress the sensor's interface if you want SSID and BSSID.

The sensor shows a short introduction the first time it runs for a user. That introduction tells the user that macOS requires Location permission to report the Wi-Fi network name (SSID) and access point (BSSID), and gives them the button to grant it. Two keys hide it:

• OrbSkipIntroduction hides the introduction and immediately prompts for permissions. The user sees the macOS Location prompt with nothing to explain why Orb is asking.
• OrbEnableRestrictions hides the introduction and stops the sensor requesting Location at all, unless you also set OrbEnableLocationPrompt. The user is never asked, and SSID and BSSID stay empty. Nothing in the console says why.

Without Location, the introduction reports that Wi-Fi details are unavailable and offers Open Location Settings:

Once Location is granted, it confirms that Wi-Fi details are enabled:

Monitoring works either way. Only the Wi-Fi network name and access point identifier depend on this permission, and Orb does not collect geographic coordinates.

On any deployment where you want per-network detail, leave both keys unset or set them to false. Set OrbEnableRestrictions to true only if you accept losing SSID and BSSID.

Upload the profile to Intune

1. Sign in to the Microsoft Intune admin center.

2. Go to Devices → macOS → Configuration, and select Create → New Policy.

3. Set Profile type to Templates, choose Custom, and select Create.

4. Give the profile a name, for example Orb Sensor Configuration, then select Next.

5. Set Custom configuration profile name to Orb Sensor Configuration, leave Deployment channel set to Device channel, upload orb-sensor.mobileconfig, and select Next.

   Intune shows the file it parsed. Check that it contains your token and the net.orb.orb payload type before you continue.

6. On Assignments, add the device group you will deploy the sensor to, then select Next.

7. Review and select Create.

Allow the sensor's background item

On macOS 13 and later, a newly installed LaunchAgent shows the user a Background Items Added notification, and the user can disable it in System Settings → General → Login Items & Extensions. A disabled agent stops the sensor from reporting, and the package deliberately does not re-enable an agent an administrator or user has turned off.

Deploy a second custom profile containing a Service Management payload so the agent is managed, always enabled, and not user-removable. Save this as orb-sensor-loginitem.mobileconfig, replacing the two UUIDs as before:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.servicemanagement</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>net.orb.orb.loginitems</string>
            <key>PayloadUUID</key>
            <string>REPLACE-WITH-UUID-3</string>
            <key>PayloadDisplayName</key>
            <string>Orb Sensor Login Item</string>
            <key>PayloadOrganization</key>
            <string>Your Organization</string>
            <key>Rules</key>
            <array>
                <dict>
                    <key>RuleType</key>
                    <string>TeamIdentifier</string>
                    <key>RuleValue</key>
                    <string>YL5R46QP4A</string>
                </dict>
            </array>
        </dict>
    </array>
    <key>PayloadDisplayName</key>
    <string>Orb Sensor Login Item</string>
    <key>PayloadIdentifier</key>
    <string>net.orb.orb.loginitems.configuration</string>
    <key>PayloadOrganization</key>
    <string>Your Organization</string>
    <key>PayloadRemovalDisallowed</key>
    <false/>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>REPLACE-WITH-UUID-4</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>PayloadScope</key>
    <string>System</string>
</dict>
</plist>

Upload it the same way as the configuration profile above, and assign it to the same group.

Add the sensor package

1. Go to Apps → macOS → macOS apps, and select Create.

2. Set App type to macOS app (PKG), and select Select.

   

3. On App information, select Select app package file, upload orb-sensor.pkg, and select OK.

   Intune reads the package and reports its name, platform and size before you confirm.

4. Correct the metadata, then select Next.

   Intune pre-fills Name and Description with the package filename, which is not what you want users or reports to see. Replace Name with Orb Sensor and write a real description. Publisher is required and is left empty — set it to Orb Forge Inc.

5. On Program, leave both the pre-install and post-install script boxes empty. The package runs its own pre- and post-install scripts, which create the launchd jobs, the log directory and the CLI symlink. Select Next.

6. On Requirements, set Minimum operating system to macOS Big Sur 11.0, then select Next.

7. On Detection rules, confirm the included app Intune read from the package is net.orb.sensor, with the version you are deploying.

   Set Ignore app version to match how you manage updates. It defaults to Yes.

   Setting	Use when
   No	Intune owns the version. Intune reinstalls whenever the installed version differs from the package. Pair this with disabling the sensor's own updater — see Control updates.
   Yes	The sensor self-updates. Intune installs it once and stops checking the version.

   Warning

   Do not set Ignore app version to No while the sensor's own updater is still enabled. The updater moves the Mac to a newer version, Intune sees a version that no longer matches the package, and reinstalls the older one — the two fight each other indefinitely.
   :::
   8. On Assignments, add your device group under Required, then select Next.
   9. Review and select Create.

The app's Properties page afterwards shows the minimum operating system, the detection rule and the assignment together, which is the quickest way to confirm the deployment is configured as intended:

Verify the deployment

In the admin center, open the app and review Overview and Device install status.

Once a Mac has installed the sensor, the app's Overview reports it:

To make a Mac check in immediately rather than waiting for its next cycle, use Sync on the device in the admin center. This is the more reliable lever: it drives the MDM channel, which delivers configuration profiles within seconds. Company Portal → Devices → ⋯ → Check status on the Mac does the same thing from the device side.