> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace ONE

> Deploy AI Watch to macOS via Workspace ONE using the signed `.pkg` and Custom Attribute–parameterized profile. Detect, endpoint modes, and Sessions ship in one package.

> [!NOTE]
>
> Migrating from the legacy script-based Detect rollout? Delete the legacy MDM script and its PPPC profile before you scope the `.pkg`; AI Watch `0.31.14` or newer retires the old `runlayer-scan` agent during install. Then follow [Legacy macOS Detect Cleanup](https://docs.runlayer.com/shadow-ai/deploy/macos-cleanup-script-deployment.md) to revoke the legacy org API key and tidy user space.

## Overview

A signed, notarized `aiwatch` binary installs once per device via `.pkg`. Tenant config — the host and a single **organization API key** — is pushed via an MDM Configuration Profile; everything else (mode, Sessions, optional discovery, scan tuning) is managed in Runlayer settings and fetched by the device. {overviewTrailer_0}

## Capabilities

All behaviors ship in the **same** `.pkg` and a **single** deployment profile that combines the tenant config, PPPC / Full Disk Access, and Login Items payloads. The tenant-config payload supplies just the host and organization API key. Devices refresh behavior — **Monitor / Protect / Enforce** mode, **Collect session data**, optional discovery, and **Advanced scan settings** — from **Settings → AI Watch → Manage settings** during the 15-minute hook reconcile; no profile edit or re-push. AI Watch `0.29.6` or newer can also install or remove the managed Chrome and Firefox extensions from the **Browser extension** tab there, and `0.30.13` or newer adds Edge.

If you need multiple tenant configurations (different host or key), deploy one copy of the profile per group (the PPPC and Login Items payloads it carries are identical across copies; only the tenant-config values differ).

Project and client-config detection is always enabled after AI Watch is installed. Before the first successful settings sync, the endpoint starts in Monitor with Sessions and optional runtime discovery disabled, so no hooks are installed. One organization API key authenticates AI Watch scans, hooks, session events, and managed updates; no enrollment keys are required.

| Capability | Configuration | What it does |
| - | - | - |
| **Detect** | Always on | Discovers AI clients, shadow MCP servers, skills, and plugins from project and client configuration files |
| **Running processes** | `DetectProcesses` / `AIWATCH_DETECT_PROCESSES` | Discovers AI tooling and configured MCP servers from running processes and listening sockets |
| **Containers and WSL** | `DetectContainers` / `AIWATCH_DETECT_CONTAINERS` | Performs read-only MCP config, skill, and agent-definition discovery inside running Docker, Podman, or nerdctl containers through a Docker-CLI-compatible CLI or local Engine API socket; on Linux, also scans k3s through root-only `k3s crictl`; on Windows, also scans bounded WSL home project trees |
| **Monitor** | `Mode=monitor` / `AIWATCH_MODE=monitor` | Reports endpoint hook activity without applying scanner or governance decisions |
| **Protect** | `Mode=protect` / `AIWATCH_MODE=protect` | Applies scanner-configured Block and Mask decisions plus fail-open, allow-unless-denied MCP source governance; explicit denylist matches are blocked |
| **Enforce** | `Mode=enforce` / `AIWATCH_MODE=enforce` | Applies scanner and local policy decisions to non-MCP tools plus fail-closed, deny-by-default MCP source governance; managed MCP calls scan at the gateway |
| **Sessions** | `Sessions` / `AIWATCH_SESSIONS` | Installs the full event hook set for [Sessions](https://docs.runlayer.com/platform-sessions.md) telemetry |
| **Track MCP tool usage without content** | `MCPUsageMetadata` (Monitor mode, Sessions off) | Installs one lightweight MCP pre-call hook per supported client that reports only the client, tool name, MCP server name, and device/user identity — never request arguments, responses, session content, or transcripts |

* **Running-process and container discovery** are disabled until the synced settings enable them.
* **Monitor** is the default mode.
* **Sessions and hooks fail closed before settings sync.** A successful settings sync or an explicit legacy MDM `Sessions=true` / Protect / Enforce setting enables them.
* **Sessions coverage follows the client surface.** Installing the full hook set does not make a client emit events it does not support. Cursor's classic IDE and Agents Window load the endpoint hook config, while Cursor CLI emits a subset. Cursor Cloud Agents require the separate [repository/team hook collector](https://docs.runlayer.com/shadow-ai/cursor-cloud-agents.md); it is monitor-only and does not inherit endpoint configuration.

Hooks are installed whenever Mode is Protect/Enforce, Sessions is enabled, or **Track MCP tool usage without content** is enabled; otherwise AI Watch removes stale Runlayer hooks while preserving third-party hooks.

> [!NOTE]
>
> **Legacy fleets only:** on AI Watch builds that predate settings sync, push the native keys manually and pair them — Monitor with `Enforcement=false`, Protect and Enforce with `Enforcement=true`. A valid `Mode` value overrides the legacy `Enforcement` boolean.

On macOS and Windows, admins can change Mode, Sessions, process/container discovery, project depth, and project timeout from **Settings → AI Watch → Manage settings**. Devices fetch the complete settings snapshot during the privileged hook reconcile, which runs every 15 minutes, without an MDM policy update. The same settings page can install or remove the managed Chrome, Edge, and Firefox extensions and configure their mode and Sessions behavior without an MDM policy update. See [Browser extension](https://docs.runlayer.com/shadow-ai/browser-extension.md) for the AI Watch version each browser and platform requires. The tenant host, organization API key, and CPU/memory limits remain MDM-owned.

**Advanced scan tuning (optional).** Detect scans walk each user's home directory to a bounded depth within a per-scan time budget, and keep CPU and memory use within configurable caps. The defaults fit most fleets — override them only if scans miss deeply-nested project configs (raise depth), run out of time on very large home directories (raise timeout), or you want a smaller footprint on constrained hosts (lower the CPU / memory caps).

| Setting | Configuration | Default | Range |
| - | - | - | - |
| **Project depth** | `ProjectDepth` | `7` | `1`–`20` |
| **Project timeout** | `ProjectTimeout` | `60`s | `1`–`300`s |
| **CPU cores** | `CpuCores` / `AIWATCH_CPU_CORES` | half the logical cores | `1`–logical cores |
| **Max CPU percent** | `MaxCpuPercent` / `AIWATCH_MAX_CPU_PERCENT` | `50` | `5`–`100` |
| **Memory limit (MB)** | `MemoryLimitMb` / `AIWATCH_MEMORY_LIMIT_MB` | `1024` | `512`–`8192` |

All are integers. Project depth and timeout are delivered by the Runlayer settings sync on macOS and Windows; native MDM values remain a legacy fallback. CPU and memory caps remain MDM-owned (`<integer>` on macOS, matching `AIWATCH_*` MSI properties on Windows). Omit them to keep the defaults. Values outside the range are clamped; non-integer or non-positive values are ignored. The CPU / memory caps are best-effort: the scan is throttled to stay within the configured CPU budget and aborts if it exceeds the memory ceiling.

## Prerequisites

* Workspace ONE admin access for the target Organization Group.
* Devices running **macOS 14 (Sonoma) or newer**. The packaged binary does not load on macOS 13 or older; for those devices, use the [manual CLI path](https://docs.runlayer.com/shadow-ai/detect.md#manual-installation) instead.
* 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 **Shadow AI Scan** role. Don't create one by hand — the setup wizard in **Settings → MDM configuration** mints it when you create the configuration and pre-fills it into the downloaded profile. Only a wizard-minted key links devices to the configuration card. The same key authenticates scanning, enforcement, sessions, and managed updates.
* Your Runlayer tenant host URL (e.g. `https://your-instance.runlayer.com`).

> [!NOTE]
>
> The macOS package supports Apple Silicon (`arm64`). For Intel Macs or other
> architectures, use the [manual CLI path](https://docs.runlayer.com/shadow-ai/detect.md#manual-installation)
> or contact your Runlayer account team.

## Artifacts

| File | Purpose |
| - | - |
| `aiwatch-<version>-macos-arm64.pkg` | Signed + notarized installer (single `aiwatch` binary + scan LaunchAgent + hook bootstrap + hourly root update daemon). The wizard serves the version selected by your Client Updates policy |
| `com.runlayer.aiwatch.ws1.mobileconfig` | {tenantConfigPurpose_0 ?? "Single deployment profile: bootstrap tenant config (host + org API key), Full Disk Access / TCC grants, and macOS 13+ Login Items pre-approval in one file (downloads pre-filled from the wizard, or hand-edit the template)."} |

Automatic updates are always on. The updater installs the version selected by your Client Updates policy; pin a version there to control what devices run.

> [!WARNING]
>
> **Deploy the Configuration Profile before the `.pkg`.** The profile 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.

> [!NOTE]
>
> **Migrating from the split profiles?** Earlier releases shipped three separate profiles (`com.runlayer.aiwatch.config.mobileconfig`, `com.runlayer.aiwatch.pppc.mobileconfig`, `com.runlayer.aiwatch.loginitems.mobileconfig`). The merged profile uses a new profile identifier, so it does **not** supersede them automatically — unscope/remove the three legacy profiles when you scope the merged one to avoid duplicate payloads.

## Deployment

**1. Define Custom Attributes (one-time per Organization Group)**

1. **Devices → Provisioning → Custom Attributes → Add**.
2. `CustomAttribute1` → set value to your tenant host URL (e.g. `https://your-instance.runlayer.com`).
3. `CustomAttribute2` → set value to your org API key secret (`rl_org_...`).

**2. Upload the WS1 deployment profile**

1. **Devices → Profiles → Add → Upload**.
2. Upload `com.runlayer.aiwatch.ws1.mobileconfig` as-is. Workspace ONE substitutes `{CustomAttribute1}` and `{CustomAttribute2}` at deploy time. The PPPC and Login Items payloads it carries are pre-pinned to Developer ID team `AF2M8HC7A2` — no edits.
3. Assign it to your target Smart Group.

**3. Upload the .pkg**

1. **Apps & Books → Internal → Add Application**.
2. Upload `aiwatch-<version>-macos-arm64.pkg`.
3. Assign to the same Smart Group.

After deployment, change Mode, Sessions, optional process/container discovery, project depth, or project timeout from **Settings → AI Watch → Manage settings**; connected devices refresh them on their next hook reconcile, within about 15 minutes. On AI Watch `0.29.6` or newer, open the **Browser extension** tab and turn on **Install browser extension** to install managed Chrome and Firefox, plus Edge on `0.30.13` or newer, without changing or re-publishing the profile. To rotate the host or API key, update the Custom Attributes and re-publish the profile. Optional MDM-owned values such as resource limits and identity overrides can be added to the profile's tenant-config payload as literal values. No `.pkg` reinstall.

## Verification

On a test Mac after installation and configuration:

```bash theme={null}
# 1. .pkg installed (binary + scan agent + hook daemon agent + bootstrap + updater)?
test -x /usr/local/bin/aiwatch && \
  test -f /Library/LaunchAgents/com.runlayer.aiwatch.plist && \
  test -f /Library/LaunchAgents/com.runlayer.aiwatch.daemon.plist && \
  test -f /Library/LaunchDaemons/com.runlayer.aiwatch.bootstrap.plist && \
  test -f /Library/LaunchDaemons/com.runlayer.aiwatch.update.plist && \
  echo "binary + scan agent + daemon agent + bootstrap + updater OK"

# 2. Signature + notarization?
pkgutil --check-signature /path/to/aiwatch-<version>-macos-arm64.pkg
codesign -dv --verbose=4 /usr/local/lib/runlayer/aiwatch/aiwatch
# Expect: Authority=Developer ID Application: Anysource Inc. (AF2M8HC7A2)
#         Identifier=com.runlayer.aiwatch

# 3. Managed or local Test Device preferences configured (host + org API key)?
defaults read /Library/Managed\ Preferences/com.runlayer.aiwatch.plist 2>/dev/null || true
defaults read /Library/Preferences/com.runlayer.aiwatch.plist 2>/dev/null || true

# 4. Scan agent loaded for the console user?
launchctl print "gui/$(id -u)/com.runlayer.aiwatch"

# 4b. Hook daemon running for the console user?
/usr/local/bin/aiwatch daemon status

# 5. Bootstrap and hourly update daemons loaded in the system domain?
# "Could not find service" after a reboot: see Troubleshooting.
sudo launchctl print system/com.runlayer.aiwatch.bootstrap
sudo launchctl print system/com.runlayer.aiwatch.update

# 6. Background item registered (macOS 13+)?
sfltool dumpbtm | grep -i runlayer

# 7. Full Disk Access activity visible to TCC?
sudo log show --predicate 'subsystem == "com.apple.TCC"' --last 5m | grep -i aiwatch

# 8. Trigger an immediate scan
/usr/local/bin/aiwatch scan

# 9. (Protect, Enforce, or Sessions) Confirm hooks are installed for the console user
sudo /usr/local/bin/aiwatch setup hooks check --mdm
# Expect: exit 0 (compliant). Exit 1 = hook configs drifted (the next bootstrap tick rewrites them).

# 10. View process activity; update failures also appear as a non-zero
# last exit code in the launchctl output from step 5.
log show --predicate 'process == "aiwatch"' --last 1h
# Tail in real time:
log stream --predicate 'process == "aiwatch"'
```

In the Runlayer dashboard, navigate to **Shadow AI → Devices** and confirm the test Mac appears.

## Common post-deploy issues

> [accordion] Users see 'Background Item Added' after install
>
> On a manual test-device install, this one-time macOS 13+ notification is expected because no MDM Login Items profile pre-approves the scan LaunchAgent.
>
> On a managed deployment, confirm `com.runlayer.aiwatch.mobileconfig` (which carries the Login Items payload) is scoped to the same device group as the `.pkg`, then force an MDM sync and check:
>
> ```bash theme={null}
> sfltool dumpbtm | grep -i runlayer
> ```
>
> Expect the Runlayer item to show `enabled allowed visible`.

> [accordion] Gatekeeper blocks the package
>
> Verify you are deploying the official signed and notarized release artifact:
>
> ```bash theme={null}
> pkgutil --check-signature /path/to/aiwatch-<version>-macos-arm64.pkg
> spctl --assess --type install -vv /path/to/aiwatch-<version>-macos-arm64.pkg
> ```
>
> Expected: a Developer ID Installer signature for Anysource Inc. and `source=Notarized Developer ID`.

> [accordion] Full Disk Access is enabled but TCC still denies access
>
> For a manual install, confirm `/usr/local/lib/runlayer/aiwatch/aiwatch` is enabled under **System Settings → Privacy & Security → Full Disk Access**. For MDM, the PPPC profile pins Full Disk Access to identifier `com.runlayer.aiwatch` and Developer ID team `AF2M8HC7A2`.
>
> Confirm the installed binary matches:
>
> ```bash theme={null}
> codesign -dv --verbose=4 /usr/local/lib/runlayer/aiwatch/aiwatch
> ```
>
> Expected: `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-minute `StartInterval`. Most tenants don't need to change it, and the interval is an operational tuning knob, not a security control — Detect coverage comes from the scan itself, not its cadence. On a managed fleet, push the script below via your MDM's recurring-script mechanism (Jamf Policy, Kandji Custom Script, SimpleMDM Script, etc.). On a manual test Mac, run it directly with administrator access:

```bash theme={null}
#!/bin/bash
set -euo pipefail
PLIST=/Library/LaunchAgents/com.runlayer.aiwatch.plist
INTERVAL=1800   # 30 min — edit per tenant
/usr/libexec/PlistBuddy -c "Set :StartInterval ${INTERVAL}" "$PLIST"

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.aiwatch" 2>/dev/null || true
    launchctl bootstrap "gui/${CONSOLE_UID}" "$PLIST" 2>/dev/null || true
fi
```

> [!NOTE]
>
> 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

The root `com.runlayer.aiwatch.update` LaunchDaemon checks hourly and installs the signed + notarized `.pkg` at the version selected by your Runlayer tenant. An MDM Custom App push or another manual `installer` run remains a fallback, but the next hourly tick will restore the selected version. To hold a manually pushed version, pin it in Client Updates first.

Upgrades replace the previous `/usr/local/lib/runlayer/aiwatch/` install cleanly, so obsolete modules and version metadata cannot survive an upgrade or rollback. The separate Runlayer CLI installation is preserved. Mid-scan upgrades are safe — a running scan finishes on the old version, and the next LaunchAgent tick picks up the new one.

MDM Configuration Profiles are unchanged across version upgrades. Preferences written manually under `com.runlayer.aiwatch` also remain in place.

> [!WARNING]
>
> If you've overridden `StartInterval` via Custom Script, the upgrade resets it to the bundled default. Re-apply the override script on a recurring schedule.

## Uninstall

For full package and hook cleanup guidance, see [Remove AI Watch](https://docs.runlayer.com/shadow-ai/deploy/remove.md).

## Troubleshooting

For deployment diagnostics and common macOS package issues, see [Troubleshooting](https://docs.runlayer.com/shadow-ai/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.