Getting Started
Trust CenterTourStatus PageSupport

Install (Generic MDM)

Deploy the macOS forwarder through any MDM. Three configuration profile payloads have to land before the installer runs, and the order is not negotiable.

The macOS forwarder collects files from Intel and Apple Silicon Macs, but unlike Windows and Linux it cannot be installed and left to configure itself. macOS requires the operating system's permission for a system extension and for full disk access, and on a managed fleet that permission arrives as configuration profiles from your MDM.

Push the profiles first, then the package. If the payloads are missing or wrong when the installer runs, the install fails and the machine needs remediation -- one at a time, by hand, on however many endpoints you sent it to.

📘

Using Jamf Pro or Kandji? Those have their own pages with the exact screens: Jamf Pro, Kandji. This page is for everything else.

What you need first

🚧

Do not start with your crown jewels

The forwarder's first act is a full-disk backscan, which is I/O-heavy for a few hours and then subsides. Treat your first several installs as sacrificial: they upload the most unique files, and every later install is cheaper because Stairwell already knows what the earlier ones sent. See Forwarder Performance Tuning.

The three payloads

The Download Center carries example configuration profiles with all of these already set, which is usually faster than building them by hand.

❗️

Apart from your own environment ID and token, every value below must be written exactly as it appears here. These are string comparisons made by macOS, and a single wrong character fails the install rather than degrading it.

The bundle identifier reads com.stairwell.Inception.ProcessMonitor, and that is correct as written. It is the identifier the shipped macOS binary is signed with, so macOS matches on it literally. Do not adjust it to look tidier.

1. System Extensions

  • Bundle Identifier: com.stairwell.Inception.ProcessMonitor
  • Team Identifier: 677UQVFGY8

This is what allows the forwarder's process monitor to load at all.

2. Privacy Preferences Policy Control

  • Bundle Identifier:
com.stairwell.Inception.ProcessMonitor
  • Code Requirement:
anchor apple generic and identifier "com.stairwell.Inception.ProcessMonitor" and (certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "677UQVFGY8")
  • SystemPolicyAllFiles: Enabled / Allow (your MDM may word this differently)

SystemPolicyAllFiles is Full Disk Access. Without it the forwarder runs and reports in while seeing only the small portion of the disk macOS lets any unprivileged process see -- a quiet failure that looks like a successful deployment until someone asks why coverage is thin.

3. Stairwell Preferences

Your MDM may call this a Managed Preferences, Custom Settings, or Application & Custom Settings payload.

  • Payload: com.stairwell.Inception.ProcessMonitor
  • Key: EnvId → your environment ID
  • Key: RegistrationToken → your authentication token

Optionally, while you are getting the first machines working:

  • Key: Debug → True

Turn Debug back off once the deployment is healthy.

One further optional key belongs here:

  • Key: STAIRWELL_REGISTRATION_KEY → a stable, unique value for the machine

Without it the forwarder identifies itself by computer name plus primary MAC address. That is correct for most fleets, and wrong for two: machines whose MAC changes register a second time as a duplicate asset, and machines imaged from a template that already carried the forwarder collide into a single asset. Set this only if one of those describes your estate, and set it before the first registration -- it is read then and not again. See Asset Identifiers.

Push all three payloads to the target machines and confirm they have landed before you deploy the package.

Install the package

With the profiles in place, deploy the current forwarder package from the macOS Forwarder downloads using whatever mechanism your MDM provides.

Verify the profiles applied to a pilot machine and that the pilot install succeeded before you scale out. A profile that failed to deploy produces a failed install, and discovering that on ten machines is a very different afternoon from discovering it on a thousand.

Confirm it worked

  1. Sign in at app.stairwell.com.
  2. Open Assets and find the new asset.
  3. Check the All Objects count.

Ingestion takes a few minutes to become visible. An asset that appears but whose object count stays at zero is the Full Disk Access symptom described above -- check the PPPC payload actually applied before you look anywhere else. See macOS Troubleshooting.

What should I read next?

Updated 19 days ago

Did this page help you?