Managed deployment on macOS

Push the macOS observer to a fleet through your MDM or RMM. You push one .pkg and two configuration profiles, and each Mac joins this organization. Employees do not sign in, and there is no per-machine key to manage. Every Mac needs macOS 15 (Sequoia) or later.

Which path you are on

One question decides everything that follows: can your MDM substitute a per-device variable into a custom profile?

That is what lets a single profile attribute each Mac to the person using it. Jamf Pro and Kandji expand $EMAIL; Intune expands {{userprincipalname}}. JumpCloud and RMM-first tools like NinjaOne do not expand anything.

Substituting MDM

The profile you downloaded already carries the token and the right variable. Upload it as-is. Push it with the certificate profile and the .pkg, and you are done.

Scope the profile to land before or with the package. The app reads managed configuration at first launch, so a profile that arrives later still works on the next launch, but that first launch will have shown the employee the ordinary onboarding screen.

Deploying to a Mac that is already running Proxon converts it. The Mac notices your configuration the first time it sees it, re-enrolls against the token in it, and is filed under IT from then on. Nobody signs out, and nobody touches the machine. This is the case if you rolled out self-serve first and are adding management later.

The same holds for a correction. Push a profile with a fixed token or a fixed address and the fleet picks it up within minutes, with nothing asked of the people using the Macs.

No substitution

The profile you downloaded for this path carries no enrollment token and no email address, because your tool cannot fill either one in per device. Both instead ride in a file your script writes to every Mac.

You can put both in that one file, and you can also split them. Proxon resolves each value on its own: the token comes from the profile when the profile carries one, because that is the copy macOS itself vouches for; the address comes from whichever source is closest to the individual Mac, which means enrollment.json wins over a profile.

That split is the useful shape on this path. Keep the token in the profile, where it is delivered and attested by your MDM once for the whole fleet, and let your script write only the per-device address into the file.

Push both profiles and the .pkg as usual, then have your tool run a script that writes /Library/Application Support/Proxon/enrollment.json as root:wheel, mode 0644:

Write the file this way, to a temporary file and then mv, rather than straight into enrollment.json. A running Proxon app re-reads the file, and a file it reads halfway through being written looks damaged. A damaged enrollment.json does not fall back to the employee connecting by hand: Proxon stays managed and holds enrollment until the file is fixed.

The token is the same for every Mac. The address is not, so pull it from whatever per-device source your tool has, and keep the token itself in a secret variable rather than in the script body.

Run the script before Proxon first launches. A Mac that has already enrolled will not redo it.

What the profile pre-approves

Each payload removes one approval dialog the employee would otherwise face:

• System extension. Allow-lists Proxon's network-capture extension by Team ID (4JDW2S2CK4) and bundle id, so it loads without the System Extension Blocked prompt.
• Privacy permissions. Pre-grants Accessibility, to read the foreground window's title, and Calendar, to count meetings in progress. Counts only, never titles or attendees.
• Browser extension. Force-installs the Proxon extension on managed Chrome, Edge, and Firefox. Safari is separate, and is covered under Browsers.
• Managed settings. The enrollment token and the per-device address, on the substituting path only. This is also the payload that carries the optional release-channel key, covered under Release channels.

Signing

You do not need a signed profile, and on the substituting path you should not want one. A profile delivered over MDM is trusted because the MDM channel is trusted, and some tools sign it themselves on upload.

A signature freezes the contents. Anything meant to be filled in per device has to be concrete before signing, so a signed profile and a per-device variable are mutually exclusive: sign one containing $EMAIL and every Mac receives that literal string.

Proxon refuses an address that is still an unexpanded variable rather than attributing anyone to it, and each affected Mac says so on its row in Org Settings, Devices. So the mistake is visible and correctable centrally instead of silent — but those Macs are unattributed until you push a profile that carries a real address, or set each one's owner by hand (see Owner attribution).

Signing earns its place in two cases. If you install the profile by hand on each Mac rather than through an MDM, macOS flags an unsigned one as Unverified. And your change control may require a signed artifact for its records.

If either applies, email support@proxon.ai. We sign after your token is in place, so there is no generic pre-signed profile we can publish, and the file we return carries no per-device variable.

Owner attribution

Proxon resolves the owner of each Mac in this order, stopping at the first hit:

1. The address from managed configuration, whether that came from the profile or from enrollment.json. This always wins.
2. The console user's directory record, meaning the logged-in user's email from Open Directory, including the local node and any directory the Mac is bound to, such as Platform SSO.
3. Unattributed, if neither produces a plausible email address.

A bare short username like ada is never promoted to an address, since attributing a Mac to the wrong person is worse than leaving it unassigned. To give an unattributed Mac an owner, or to correct one, push the right address in the profile or enrollment.json. The Mac re-enrolls under it within minutes, with nothing to re-install (see Substituting MDM).

An organisation owner or admin can also set the owner by hand. In Org Settings, open Devices, find the Mac under Enrolled devices, open the menu on its row, and choose Set owner; Remove owner, on the same menu, clears one. This is one device at a time, and it does not correct the profile: the next enrollment that finds an address puts that address's person back as the owner. For more than a few Macs, fix the address in the profile instead.

Each macOS account on a Mac enrolls it at that account's first login, because Proxon keeps its credential per account. All of them land on the same device, and the account that enrolled most recently owns it, as long as Proxon found an address for it. An enrollment that finds no address leaves the existing owner in place. So when your configuration supplies the address, that person owns the Mac whoever logs in.

Macs nobody logs into

A managed Mac enrolls when someone logs into it. Installing the .pkg and the profiles is not enough on its own, unless someone is already logged in when it installs. Proxon starts when a person logs into a macOS account, and enrollment happens at that first start. A Mac that sits at the login window and that nobody ever logs into does not enroll, apart from the Setup Assistant case below. It captures nothing, sends nothing, and does not show up in Org Settings, Devices. Nothing warns you about it, because the Mac never contacts Proxon.

Proxon also captures and sends only while someone is logged in. Nothing is captured at the login window or after everyone logs out. With fast user switching, each logged-in account runs its own copy of Proxon, but only the account that enrolled most recently keeps sending. When another account on the same Mac enrolls, the first account's copy stops sending until it next starts.

This is how Proxon works on a Mac. These Macs are affected:

• Kiosks, lab machines, and other Macs that sit at the login window with nobody logged in.
• Macs you set up ahead of time, through Automated Device Enrollment or by hand, and leave until their owner arrives.
• Shared or VDI-style images. Do not log into the image, or let it enroll, before you capture it: a copy of an enrolled image carries that enrollment with it. Copies that share one hardware identifier (IOPlatformUUID) also count as a single device in Proxon.

What to do:

• For a Mac that will have an owner, nothing, as long as the enrollment token in your profile or enrollment.json still works when they arrive. Only a Mac's first enrollment counts against the token's use limit, so keep enough uses for every Mac you staged. Keep the token unexpired and unrevoked for as long as Macs may still enroll or enroll again: a new account logging in, an owner you correct by pushing an address, or a Mac you re-image all need it. Until the owner's first login the Mac is usually missing from Org Settings, Devices. If the package installed during Setup Assistant, it may instead be listed without an owner, unless your profile or enrollment.json supplies the address. Both are expected, and the owner's first login attributes it.
• For a Mac nobody will log into, it is covered only while an account is logged in. On a kiosk or lab Mac, set macOS to log into its account automatically when it starts. macOS turns automatic login off while FileVault is on.
• Check who it was attributed to. If your profile or enrollment.json supplies an address, that person owns the Mac, whoever logs in. If not, the account that enrolled most recently with a findable address owns it, which can be a technician's account until the real owner logs in. To correct an owner, push the right address. See Owner attribution.

Browsers

The extension is the same on every browser. Only the way it gets switched on differs. If you push the profile, Chrome, Edge, and Firefox are done. Without a profile, the .pkg sets up Firefox only, because Chrome and Edge treat an extension policy as binding only when it arrives from a configuration profile, and no privileged script gets around that.

Verify

On a target Mac, once the install and the profiles have both landed, run these in order.

Updates

Proxon updates itself. The app checks hourly and installs each new signed release in the background, with nothing for the employee to click and nothing for you to repackage. To have employees choose when to install, or to pause updates for a maintenance window, see Controlling when updates install.

That holds for a managed rollout too. A Mac the .pkg landed on with nobody logged in updates exactly like one installed by hand, and so does a Mac whose owner is a standard user with no administrator rights. Nobody is asked for a password, and you do not push a new .pkg for each release.

What installs the update

The .pkg installs a background service that runs as root, com.proxon.update-helper. When the person using the Mac cannot write to /Applications, which is the ordinary case on a managed fleet, the app hands the install to that service rather than asking for an administrator password. Root performs the write, so it stops mattering who owns the app bundle or what rights the employee has.

The service does one thing, which is install the current signed Proxon release. It takes no other instruction, and it carries no enrollment token, no organization identifier, and no credential of yours. Before it installs anything, it checks the package three independent ways:

• Proxon's own release signature over the bytes it downloaded. The key it checks against is built into the service rather than read from disk, so nothing on the Mac can swap in another one.
• Gatekeeper's assessment of the package, the same check macOS runs on an installer someone opens by hand. It requires a Developer ID signature and Apple notarization.
• Proxon's Apple Team ID (4JDW2S2CK4) in the package's signing chain. Gatekeeper on its own would accept a notarized package from any Apple developer, and this check is what narrows it to ours.

A package that fails any one of the three is discarded, and nothing is installed.

If a Mac can see a new release and cannot install it, Proxon says so against that device in the console, with the reason.

Release channels

Every Mac follows the production channel, where released versions are published, and you do not have to configure anything to get that. Set a channel only if you want a pilot group on pre-release builds.

The key is update_channel, in the com.proxon.observer domain, in the same com.apple.ManagedClient.preferences payload that already carries user_email. It takes exactly two values, both lowercase. production is the released channel, and develop is the pre-release one.

The profile you download does not set the key, so an unedited profile leaves the whole fleet on production. Add it yourself for the group you want on pre-release builds, and leave it out everywhere else.

Proxon reads the key only when it arrives forced from a configuration profile. An employee can pick a channel for their own Mac in the app's Diagnostics window, and a forced value outranks that choice, which is the reason to set it centrally. Any other spelling is ignored and the Mac keeps the channel it already had, so a typo cannot move a fleet onto a channel nobody chose. Diagnostics shows the channel in effect and whether it came from your profile.

On the no-substitution path the profile you download carries no Proxon managed-settings payload. Put the key in a separate profile instead, as described in Update settings without a Proxon payload.

Controlling when updates install

Four more optional keys decide when a Mac installs an update. They go in the same com.proxon.observer domain and payload as update_channel, and they match the Windows Updates policies of the same names. The profile you download sets none of them, so an unedited profile keeps the default of installing each release as soon as it is found. If your downloaded profile has no such payload, which is the case on the no-substitution path, see Update settings without a Proxon payload.

Let employees choose when to install. Set ProxonUpdatesAutoApply to false. The Mac still checks for updates every hour and shows that one is available, but it never installs one by itself. The employee installs it by choosing Update Proxon in the Proxon menu. On a Mac installed from the .pkg, that install runs through the update service described above, so it works for a standard user with no administrator password.

Pause updates for a maintenance window. Set ProxonUpdatesDeferralWindowStart and ProxonUpdatesDeferralWindowEnd. Inside the window the Mac does not check for updates and installs nothing, even when the employee chooses Update Proxon. When the window ends, updates resume on the next hourly check. Both keys take one of two forms, and both must use the same one:

• A date and time in ISO 8601, such as 2026-12-18T17:00:00Z, for a one-off freeze. A time with no Z or offset is read as UTC.
• A time of day in 24-hour form, such as 22:00, for a window that repeats every day in the Mac's own time zone. A start later than the end crosses midnight, so 22:00 to 06:00 covers the night. A 12-hour value such as 9:00PM is not read on a Mac, even though Windows accepts it.

A daily window must leave at least 61 minutes outside it each day. The Mac checks for updates once an hour, sometimes a few seconds late, and the employee's own check is paused inside the window too, so a shorter gap could fall between two checks every day and the Mac would never update. A daily window that leaves less than 61 minutes outside it, one longer than 22 hours 59 minutes, is treated as set up wrong and pauses nothing. Windows does not have this rule and would honor such a window as written.

A one-off window cannot pause updates for more than 90 days from its start, however late its end. ProxonUpdatesMaxDeferralDays, a whole number, shortens that limit. It applies only to a date-and-time window and does nothing on its own.

A window that is set up wrong never stops updates. If only one of the two keys is set, a value cannot be read, the two use different forms, the start is not before the end, or a daily window leaves less than 61 minutes outside it, the Mac updates as normal and writes the reason to its log.

Both settings apply from the moment the profile arrives, with one exception. An update that was already downloading, or already handed to the update service, when the profile or the window arrived can still finish installing, at the latest when Proxon next quits. Later updates wait as described.

Proxon reads these keys only when they arrive forced from a configuration profile, so an employee cannot change them. To see whether a Mac is holding an update and why, run this on it:

In the JSON it prints, update.held_reason reads deferral_window while the window is open, and auto_apply_disabled when an update has been found and is waiting for the employee. It is missing when nothing is held, including on a Mac that is already up to date.

Update settings without a Proxon payload

On the no-substitution path the profile you download carries no com.proxon.observer payload, so there is nowhere in it to put update_channel or the keys under Controlling when updates install. Push them in a second, separate configuration profile instead. JumpCloud, NinjaOne and most RMM tools can deploy a custom .mobileconfig.

Proxon reads each key on its own and does not care which profile it came from. Different keys from separate profiles combine. Do not set the same key in two profiles, because which value wins is not defined. Give the extra profile its own identifiers.

A key that does not reach the Mac changes nothing: the Mac stays on its channel and installs updates as normal. We have not yet confirmed this with a live push from an MDM, so check one Mac after the profile arrives. This lists the keys the Mac actually received:

For example, to have employees choose when to install:

Replace the two UUIDs with new ones, for example from uuidgen. Add update_channel or the window keys beside ProxonUpdatesAutoApply in the same mcx_preference_settings block if you want them.

Uninstall

Removing Proxon from a Mac takes root. On a managed Mac, Proxon refuses to uninstall when an ordinary user runs it, so employees cannot remove it themselves. Run the commands below through your MDM, which runs scripts as root.

Known limits

• A Mac has one MDM of record. Proxon's profile has to come from whichever MDM already owns your Macs.
• The .pkg cannot grant the system extension or the privacy permissions on its own. Only an MDM profile can, and without one, each employee approves those once.
• Proxon's inspection certificate reaches a Mac only as a configuration profile. A Mac without it keeps working, but Proxon does not inspect its AI traffic until the profile arrives. See Traffic-inspection certificate trust.
• Enrollment happens at the app's first launch, not during the install. A DEP or Setup Assistant install has no person logged in to attribute the Mac to, so the Mac either waits for the owner's first login or enrolls without an owner, unless your profile or enrollment.json supplies the address, until then. A Mac that nobody logs into does not enroll, and Proxon captures only while someone is logged in. See Macs nobody logs into.
• Converting a Mac that is already running Proxon, and correcting a profile you have already pushed, both work fleet-wide and need nobody to touch a machine. A Mac that has never launched the app picks the change up at its next launch.
• Apple is retiring the ability to grant Accessibility through a configuration profile. When that lands, this permission stops being pre-grantable and the managed install gains an employee prompt for it. Check Apple's current release notes for the version it affects before planning around it.
• Attribution falls back to the local directory record, which some tools never populate. See the warning under Owner attribution.
• Without a configuration profile, only Firefox can be set up automatically.
• Firefox's policy does not survive a Firefox self-update, because Mozilla keeps it inside the Firefox app bundle. Re-running the .pkg restores it, and the profile avoids the problem entirely.
• Proxon installs its own updates while the app is running, so a Mac that is switched off, or that nobody has logged into yet, stays on the build it has until somebody uses it. See Updates.
• MDM consoles differ in how strictly they validate a custom profile. If yours rejects a payload or silently ignores a key, send us the error text and we will turn a fix around quickly.