macOS Deployment

The macOS package is a single signed and notarized .pkg. It installs the self-contained bundle to /usr/local/lib/runlayer/runlayer/, symlinks /usr/local/bin/runlayer, and adds two package-owned launchd jobs: an hourly root updater (com.runlayer.cli.update) and an hourly per-user scheduler (com.runlayer.cli.schedule). The updater is enabled by default but silently exits until managed Host and OrgApiKey values are available. Skill sync also defaults on but waits for Host and either SkillSyncOrgApiKey or OrgApiKey. The base deployment needs no Configuration Profiles.

Prerequisites

An MDM with package deployment — Jamf Pro, Kandji, SimpleMDM, Mosyle, Workspace ONE, Intune, or any MDM that can deploy a .pkg
Apple Silicon (arm64) Macs
The signed runlayer-<version>-macos-arm64.pkg from your Runlayer downloads access

Deployment Steps

Upload the .pkg

Upload runlayer-<version>-macos-arm64.pkg as a Custom App (or equivalent package item) in your MDM — Jamf Pro, Kandji, SimpleMDM, Mosyle, Workspace ONE, Intune, or any MDM with package deployment.

Scope to your devices

Scope the app to the device groups that should have the CLI. No profiles, PPPC grants, or additional payloads are required for the base install.

Skill sync (optional)

With managed skill sync, devices install the skills you select in Runlayer and refresh them hourly. It is enabled by default and starts working once the deployment profile below supplies the tenant host and an API key.

Push the deployment profile

Download the pre-filled com.runlayer.cli.mobileconfig from the wizard (Settings → MDM configuration) and deploy it. One profile carries two payloads: managed preferences in the dedicated com.runlayer.cli domain (Host and OrgApiKey) and Login Items pre-approval for the scheduler agent on macOS 13+, so users never see a “Background Item Added” notification.The CLI reads the com.runlayer.cli domain first, then fills missing values from com.runlayer.aiwatch. If you already deploy AI Watch, its Host and OrgApiKey work as fallbacks; use the dedicated domain only for CLI-specific values or overrides.Supported managed-preference keys:

Key	Type	Default	Value
`Host`	String	None	`https://your-tenant.runlayer.com`; required for managed updates and skill sync
`OrgApiKey`	String	None	Organization API key used by managed updates and as the skill-sync fallback
`SyncSkills`	Boolean	`true`	Set `false` to opt out of managed skill sync
`SkillSyncOrgApiKey`	String	None	An org API key with the Skill Sync role. Optional — without it the scheduler uses `OrgApiKey`.
`Username`	String	None	Overrides the detected local username for skill-sync identity. Set it to the user’s email when local account names don’t map cleanly to Runlayer users.

SyncSkills is an opt-out switch: omitting it leaves managed skill sync enabled once its required host and key are present.

To verify on a device — run a sync by hand and check its status:

runlayer skills sync

For an unattended per-user run, --username overrides identity detection and --quiet suppresses non-error output:

runlayer skills sync --username user@example.com --quiet

runlayer schedule runs all due registered tasks once, using the same entrypoint as the package’s hourly per-user scheduler. Fleet-wide, each device reports its skill-sync status on its device page under Shadow AI.

Upgrades and removal

Upgrade — once managed Host and OrgApiKey values are present, devices install the version selected by your Runlayer tenant themselves within the hour. Pin a CLI version in Client Updates to hold it. For a one-off update, run runlayer update with an organization API key. You can also push a newer .pkg through the same MDM item; installers upgrade in place.

Remove — unscope the app in your MDM, or run the following as root to remove the bundle, both launchd jobs, and the package receipt (every step tolerates already-removed state, so re-runs are safe):

# Stop the per-user scheduler agent (no-op at the login window)
CONSOLE_UID=$(stat -f %u /dev/console 2>/dev/null || echo "")
if [ -n "$CONSOLE_UID" ] && [ "$CONSOLE_UID" != "0" ]; then
  launchctl bootout "gui/${CONSOLE_UID}/com.runlayer.cli.schedule" 2>/dev/null || true
fi
# Stop the root updater
launchctl bootout system/com.runlayer.cli.update 2>/dev/null || true

# Binary symlink + bundle (a sibling AI Watch install stays untouched)
rm -f /usr/local/bin/runlayer
rm -rf /usr/local/lib/runlayer/runlayer

# launchd jobs
rm -f /Library/LaunchAgents/com.runlayer.cli.schedule.plist
rm -f /Library/LaunchDaemons/com.runlayer.cli.update.plist

# Package-owned local preferences (MDM-managed preferences stay untouched)
defaults delete /Library/Preferences/com.runlayer.cli 2>/dev/null || true
rm -f /Library/Preferences/com.runlayer.cli.plist

# Forget the receipt so a future install is a clean first-install
pkgutil --forget com.runlayer.cli 2>/dev/null || true

This does not remove the MDM-pushed com.runlayer.cli.mobileconfig profile — unscope that from the device group separately.

Verification

On a target device, confirm the binary resolves on PATH:

runlayer --version
runlayer status

Before rolling an MCP server out to users, runlayer doctor runs read-only connectivity and OAuth preflight checks against it and reports any problems it finds:

runlayer doctor <server-id-or-alias>

For fleet-level visibility, check the app’s install status in your MDM console.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Prerequisites

Deployment Steps

Skill sync (optional)

Upgrades and removal

Verification

​Prerequisites

​Deployment Steps

​Skill sync (optional)

​Upgrades and removal

​Verification

Prerequisites

Deployment Steps

Skill sync (optional)

Upgrades and removal

Verification