Mac Onboarding with Alectrona Patch

Mac Onboarding with Alectrona Patch lets administrators define a set of applications that should be installed during a device's first-run experience. It is designed for MDM enrollment workflows where a new Mac needs a curated baseline of software the moment the user logs in — and it is idempotent, so repeated triggers are no-ops once each app's install has succeeded.

Mac Onboarding is configured via the Onboarding key in the com.alectrona.patch-agent MDM domain. The agent invokes the onboarding flow automatically at startup and on configuration changes, and the same flow can be triggered manually with the patch onboard install command line tool.

Mac Onboarding is once-and-done

Each app's successful install is recorded in a persistent store. Subsequent invocations skip already-completed apps regardless of how the flow is triggered. This means you can safely re-invoke Mac Onboarding (via MDM redeploy, a script, or patch onboard install) without re-installing apps that have already landed.

Supported Inner Keys

Key	Type	Default	Purpose
CatalogIDs	Array of strings	(required)	The catalog IDs of apps to install during onboarding.
PreserveOrder	Bool	true	Install apps strictly in the order declared in CatalogIDs. Downloads remain concurrent — only the install step is sequenced.
HaltOnError	Bool	false	Stop the onboarding run as soon as an app's install fails. Useful when later apps depend on earlier ones.
SkipIfInstalled	Bool	true	Treat apps that are already installed as complete without updating them. Set to false to allow Mac Onboarding to perform an install-or-update pass on every listed app.
MaxDeviceAgeSeconds	Integer	(unset)	Optional safety gate. When set, the Patch Agent skips Mac Onboarding on devices whose age exceeds this threshold. Useful when an MDM profile is deployed fleet-wide and the admin wants to prevent Onboarding from running on existing devices. Only gates the agent-driven path; patch onboard install from the CLI is unaffected.

Common Use Cases

Basic onboarding via MDM

"Every new Mac in our fleet should have Google Chrome, Slack, and 1Password installed on first run."

The simplest Mac Onboarding configuration is just a list of CatalogIDs. The agent installs each app once during the device's initial enrollment; subsequent triggers are no-ops.

<!-- Domain: com.alectrona.patch-agent -->

<?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>Onboarding</key>
        <dict>
            <key>CatalogIDs</key>
            <array>
                <string>google-chrome</string>
                <string>slack</string>
                <string>1password</string>
            </array>
        </dict>
    </dict>
</plist>

Setup Your Mac / Jamf Setup Manager

"We use a progress-display tool like Setup Your Mac or Jamf Setup Manager to drive device enrollment, and we want it to install first so it can show progress as the rest of our onboarding apps install."

Use PreserveOrder to sequence installs in the order declared under CatalogIDs, putting your progress-display tool — swiftdialog (used by Setup Your Mac) or setup-manager (Jamf Setup Manager) — first so it can show install progress as the remaining apps land. Downloads continue to run concurrently; only the install step is sequenced. Because Patch installs this tool during onboarding, you can skip the typical pre-staged enrollment package for it in your Jamf Prestage, simplifying the configuration.

<!-- Domain: com.alectrona.patch-agent -->

<?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>Onboarding</key>
        <dict>
            <key>CatalogIDs</key>
            <array>
                <string>setup-manager</string>
                <string>google-chrome</string>
                <string>slack</string>
                <string>1password</string>
            </array>
            <key>PreserveOrder</key>
            <true/>
        </dict>
    </dict>
</plist>

Halt on error for dependency chains

"If our license tool fails to install, none of the apps that depend on it should attempt to install either."

Combine PreserveOrder with HaltOnError to stop the run as soon as any install fails. Apps that haven't been attempted yet are left pending and will be retried on the next onboarding invocation.

<!-- Domain: com.alectrona.patch-agent -->

<?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>Onboarding</key>
        <dict>
            <key>CatalogIDs</key>
            <array>
                <string>company-license-tool</string>
                <string>app-that-needs-license</string>
                <string>another-app-that-needs-license</string>
            </array>
            <key>PreserveOrder</key>
            <true/>
            <key>HaltOnError</key>
            <true/>
        </dict>
    </dict>
</plist>

Update apps already on the device

"Some of our devices already have Slack installed but we want Mac Onboarding to bring them up to the latest version too."

By default Mac Onboarding skips apps that are already installed. Set SkipIfInstalled to false to perform an install-or-update pass on every listed app; already-current apps are still recorded as complete.

<!-- Domain: com.alectrona.patch-agent -->

<?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>Onboarding</key>
        <dict>
            <key>CatalogIDs</key>
            <array>
                <string>google-chrome</string>
                <string>slack</string>
                <string>1password</string>
            </array>
            <key>SkipIfInstalled</key>
            <false/>
        </dict>
    </dict>
</plist>

Limit to newly-deployed devices

"We deploy one Onboarding profile fleet-wide because our MDM can't easily scope by enrollment date — but we don't want existing devices to start installing onboarding apps when the profile arrives."

Use MaxDeviceAgeSeconds to gate Mac Onboarding on device age. When the Patch Agent sees an Onboarding configuration, it checks how long it has been since Setup Assistant first completed on the Mac (a stable signal that survives OS upgrades and Patch reinstalls but resets on Erase All Content & Settings). If the device is older than the configured threshold, the agent logs and skips Onboarding entirely — no installs, no network requests, no completion-store writes.

A common starting value is 604800 (7 days), wide enough to handle weekend gaps and slow MDM rollouts but tight enough to filter anything older than a fresh deployment. Common alternatives: 86400 (1 day), 259200 (3 days), 2592000 (30 days).

<!-- Domain: com.alectrona.patch-agent -->

<?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>Onboarding</key>
        <dict>
            <key>CatalogIDs</key>
            <array>
                <string>google-chrome</string>
                <string>slack</string>
                <string>1password</string>
            </array>
            <key>MaxDeviceAgeSeconds</key>
            <integer>604800</integer>
        </dict>
    </dict>
</plist>

CLI invocations are not gated

The age gate only applies when the Patch Agent autonomously decides to run Onboarding. Admins running sudo patch onboard install <ids> manually — for testing or from a Self Service workflow — are never blocked by MaxDeviceAgeSeconds. The CLI is the explicit override.

Triggering Mac Onboarding from the Command Line

The patch onboard subcommand provides three commands for working with Mac Onboarding from the CLI. These are useful for testing, for Self Service workflows, and for manual reset during development.

patch onboard install

Triggers the onboarding flow with one or more catalog IDs. The same idempotency rules apply — already-completed apps are skipped — so this command can be invoked safely from postflight scripts, Self Service buttons, or test runs.

# Install three apps as part of device onboarding, preserving install order
# (already-completed apps are skipped on subsequent invocations; --preserve-order
# is the default for `onboard install`, shown here for clarity)
sudo patch onboard install microsoft-company-portal google-chrome slack --preserve-order

note

patch onboard install requires at least one app ID as a positional argument. The CLI does not read the configured Onboarding.CatalogIDs preference — that is the agent's path. CLI-driven runs are independent.

patch onboard list

Lists the catalog IDs that have already completed onboarding on this device, so administrators can verify what is recorded in the persistent store.

sudo patch onboard list

patch onboard reset

Clears the onboarding completion store. The next invocation of patch onboard install (or the next agent-driven onboarding event) will attempt every configured app again, regardless of whether it was previously marked complete. Useful during testing or after rebuilding a device's baseline.

sudo patch onboard reset

Visibility

Mac Onboarding progress is recorded in the Patch log at /var/log/alectrona-patch.log. The log captures which app IDs were targeted, the order in which installs were attempted, and which IDs reached success (and were therefore marked complete in the persistent store).

The completion store itself is inspectable via patch onboard list, which is the recommended way to verify what has and has not yet onboarded on a given device.

See Also

• Onboarding preference reference
• Installing and Updating Apps for general patch install usage