Migrating from the legacy script-based Detect rollout? Run Legacy macOS Detect Cleanup before rolling out the
.pkg so the old runlayer-scan artifacts don’t conflict with com.runlayer.aiwatch.Overview
A signed, notarizedaiwatch binary installs once per device via .pkg. Tenant config — host, a single organization API key, and the Enforcement / Sessions capability flags — is pushed via an MDM Configuration Profile.
Capabilities
All behaviors ship in the same.pkg and shared PPPC / Login Items profiles. The capability flags in the tenant-config profile decide what runs — flip a flag and re-push the profile, no .pkg reinstall.
If you need multiple configurations, deploy one tenant-config profile per group. The .pkg, PPPC profile, and Login Items profile are universal and can be reused unchanged across all configurations.
Detect is always enabled after AI Watch is installed. Enforce and Sessions are controlled by package configuration, and one organization API key authenticates scanning, enforcement, and sessions; no enrollment keys are required.
| Feature | Configuration | What it does |
|---|---|---|
| Detect | Always on | Discovers shadow MCP servers, skills, and plugins through scheduled scans |
| Enforce | Enforcement / AIWATCH_ENFORCEMENT | Installs client hooks that block unmanaged MCP sources and policy-check local tool activity |
| Sessions | Sessions / AIWATCH_SESSIONS | Installs the full event hook set for Sessions telemetry |
- Enforce is disabled by default. Set
Enforcement=true(macOS) orAIWATCH_ENFORCEMENT=1(Windows) to block unmanaged MCP sources and policy-check local tool activity. - Sessions is enabled by default. Set
Sessions=false(macOS) orAIWATCH_SESSIONS=0(Windows) to skip the full event/session hook set.
Sessions=false or AIWATCH_SESSIONS=0; omitting Sessions uses the default enabled state and installs hooks for monitoring-only telemetry.
The MDM Configuration setup wizard bakes the flag values into the downloaded profile from the Enforce policies / Collect session data toggles. When hand-editing a macOS profile, set each flag to <true/> or <false/> explicitly.
Prerequisites
- Devices enrolled via UAMDM (User-Approved MDM) or DEP/ADE. TCC payloads are ignored on manually-enrolled MDM.
- A single organization API key with the Detect Scan role minted in Settings → Organization API keys in the Runlayer dashboard. Record the secret value (
rl_org_...). The same key authenticates scanning, enforcement, and sessions. - Your Runlayer tenant host URL (e.g.
https://your-instance.runlayer.com).
Apple Silicon only for now. The current release ships an
arm64 .pkg.Artifacts
The package is a.zip named aiwatch-<version>-macos-arm64.zip. Contents:
| File | Purpose |
|---|---|
aiwatch-<version>-macos-arm64.pkg | Signed + notarized installer (single aiwatch binary + scan LaunchAgent + hook bootstrap) |
com.runlayer.aiwatch.pppc.mobileconfig | Full Disk Access / TCC grants (upload as-is) |
com.runlayer.aiwatch.loginitems.mobileconfig | Pre-approves the bundled LaunchAgents on macOS 13+ (upload as-is; LabelPrefix=com.runlayer.aiwatch covers all current and future user-context units) |
.zip yet.
Deploy the three Configuration Profiles before the
.pkg. Profiles must land in /Library/Managed Preferences/ and TCC before the bundled LaunchAgent’s first scan tick — otherwise aiwatch logs host not configured and TCC denies project-config reads until the next MDM sync.Deployment
Edit the tenant-config profile
Open
com.runlayer.aiwatch.config.mobileconfig in a text editor and replace both placeholders:| Placeholder | Replace with |
|---|---|
REPLACE_WITH_TENANT_HOST | e.g. https://your-instance.runlayer.com |
REPLACE_WITH_ORG_API_KEY | the actual rl_org_... secret |
Upload the three Configuration Profiles
For each
.mobileconfig (tenant config edited above, plus PPPC and Login Items as-is):- Library → Add New → Custom Profile → Add & Configure.
- Upload the
.mobileconfig. - Device Family: Mac.
- Assign to your target Blueprint(s).
AF2M8HC7A2 — no edits required.Upload the .pkg as a Custom App
- Library → Add New → Custom App → Add & Configure.
- Upload
aiwatch-<version>-macos-arm64.pkg. - Install Type: Audit & Enforce.
- Audit Script (optional):
test -x /usr/local/bin/aiwatch && test -f /Library/LaunchAgents/com.runlayer.aiwatch.plist— never needs updating across releases. - Assign to the same Blueprint(s).
com.runlayer.aiwatch.config.mobileconfig, bump PayloadVersion on both the inner and outer payloads, re-upload. No .pkg reinstall.
Verification
On a test Mac after MDM sync:Common post-deploy issues
Users see 'Background Item Added' after install
Users see 'Background Item Added' after install
Confirm On macOS 13+, expect the Runlayer item to show
com.runlayer.aiwatch.loginitems.mobileconfig is scoped to the same device group as the .pkg, then force an MDM sync and check:enabled allowed visible. macOS 12 and older ignore the Login Items payload; the notification control only exists on macOS 13+.Gatekeeper blocks the package
Gatekeeper blocks the package
Verify you are deploying the official signed and notarized release artifact:Expected: a Developer ID Installer signature for Anysource Inc. and
source=Notarized Developer ID.PPPC applied but TCC still denies access
PPPC applied but TCC still denies access
The PPPC profile pins Full Disk Access to identifier Expected:
com.runlayer.aiwatch and Developer ID team AF2M8HC7A2. Confirm the installed binary matches:Authority=Developer ID Application: Anysource Inc. (AF2M8HC7A2) and Identifier=com.runlayer.aiwatch. Custom or ad-hoc signed builds will not satisfy the PPPC CodeRequirement.Customize scan schedule (optional)
The bundled LaunchAgent ships with a 15-minuteStartInterval. Most tenants don’t need to change it. To override, push the script below via your MDM’s recurring-script mechanism (Jamf Policy, Kandji Custom Script, SimpleMDM Script, etc.):
The next
.pkg upgrade resets StartInterval to the bundled default — the override script must run on a recurring schedule, or be re-applied after each upgrade.Upgrade
Push the new.pkg version via your MDM’s Custom App / package mechanism. The pkgbuild receipt (com.runlayer.aiwatch) tracks every file in the install layout; installer removes any files in the old receipt not present in the new payload and atomically lays down the new tree per file. Mid-scan upgrades are safe — macOS lets you unlink an open file, the running aiwatch keeps its mapped .dylib pages until the next LaunchAgent tick picks up the new version.
The three Configuration Profiles (tenant config, PPPC, Login Items) are unchanged across version upgrades.