> ## 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. # Deploy AI Watch > Deploy AI Watch once, then configure Monitor, Protect, Enforce, and Sessions AI Watch ships as one signed package per operating system. Deploy it once, then manage its behavior from Runlayer or package configuration. macOS and Windows are supported equally: both packages provide the same Monitor, Protect, Enforce, and Sessions behavior with the same configuration model — only the delivery mechanism differs (Configuration Profiles on macOS, MSI properties / registry on Windows). See [platform support](#package-and-platform-support) for supported architectures and Linux. ## Features Project and client-config detection is always enabled after AI Watch is installed. Endpoint behavior is selected with `Mode`; Sessions and optional runtime discovery are controlled independently. One organization API key authenticates AI Watch scans, hooks, session events, and macOS 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** | `DetectContainers` / `AIWATCH_DETECT_CONTAINERS` | Performs read-only MCP config, skill, and agent-definition discovery inside running Docker containers through the Docker CLI or local Engine API socket; on Linux, also scans k3s through root-only `k3s crictl` | | **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](/platform-sessions) telemetry | * **Running-process and container discovery** are disabled by default. Set their macOS/Linux keys to `true` or Windows properties to `1` to opt in. * **Monitor** is the default mode. * **Sessions** is enabled by default. Set `Sessions=false` (macOS) or `AIWATCH_SESSIONS=0` (Windows) to skip the full event/session hook set. `Mode` overrides the legacy `Enforcement` boolean when it contains a valid value. If `Mode` is absent or invalid, `Enforcement=true` maps to Enforce and `Enforcement=false` or absent maps to Monitor. Generated deployment artifacts still include `Enforcement` for older AI Watch versions: Monitor writes `false`, while Protect and Enforce write `true`. Mode-aware clients apply the exact selected mode; an older client receiving Protect falls back to Enforce rather than silently monitoring, but does not have Protect's exact direct-MCP scanner path. Hook installation follows the combined capability state: AI Watch installs hook configs when Mode is Protect/Enforce or Sessions is enabled. Detect-only uses Monitor with Sessions disabled; omitting Sessions uses the default enabled state and installs hooks for Monitor telemetry. On current macOS and Windows packages, admins can change Mode, Sessions, process/container discovery, project depth, and project timeout from **Settings → MDM configuration → Manage settings**. Devices fetch the complete settings snapshot during the privileged hook reconcile, typically within an hour, without an MDM policy update. The tenant host, organization API key, `AutoUpdate`, CPU/memory limits, and browser-extension settings 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 a cooperative in-process governor keeps CPU and memory use within soft 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 to constrain the scan's footprint on constrained hosts (lower the CPU / memory caps). | Setting | Configuration | Default | Range | | --------------------- | -------------------------------------------- | ---------------------- | ----------------- | | **Project depth** | `ProjectDepth` / `AIWATCH_PROJECT_DEPTH` | `7` | `1`–`20` | | **Project timeout** | `ProjectTimeout` / `AIWATCH_PROJECT_TIMEOUT` | `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` | `128`–`8192` | All are integers — macOS `` in the tenant-config profile, Windows `REG_DWORD` via the matching MSI `AIWATCH_*` property. Omit the keys to keep the defaults. Values outside the range are clamped into it; non-integer or non-positive values are ignored and the default applies. The CPU / memory caps are best-effort: the governor throttles the scan to hold the CPU duty cycle (`max(0.05, min(cpu_cores, MaxCpuPercent% × logical_cores))` cores) and aborts the scan if its Python-heap high-water mark exceeds the memory ceiling. ## Package and platform support No. The signed `.pkg` / `.msi` is the same artifact for every customer — nothing tenant-specific is compiled into it. Your tenant host and organization API key are supplied separately through MDM configuration (the macOS Configuration Profile, or the Windows MSI properties / registry), not baked into the binary. That means the package can be verified once (signature, notarization) and reused unchanged across all of your configurations. No. The MDM package is fully self-contained: it installs a single signed `aiwatch` binary with its runtime bundled. There is no Python, `uv`, or separate CLI install required on managed devices. The `uv tool install runlayer` CLI path documented on [Detect](/shadow-ai/detect#manual-installation) and [Enforce](/shadow-ai/enforce#manual-installation-single-device) is only for manual, single-device testing. | Platform | Managed deployment | Notes | | ------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | macOS (Apple Silicon / arm64) | Signed + notarized `.pkg` | Released artifact `aiwatch--macos-arm64.pkg` | | Windows (x64) | Signed `.msi` wrapped for Intune | Windows 10 1809+ / 11, 64-bit | | Linux (x86\_64) | `.deb` / `.rpm` / container (**Detect only**) | Ubuntu 22.04+, Debian 12+, RHEL/Rocky/Alma 9+, Amazon Linux 2023, current Fedora — see [Linux](/shadow-ai/deploy/linux) or [Container](/shadow-ai/deploy/container) | | Linux, legacy distros (x86\_64) | `glibc2.17`-tagged `.deb` / `.rpm` (**Detect only**) | RHEL/CentOS 7+, Amazon Linux 2, Ubuntu 14.04+, Debian 8+ — see [Legacy distributions](/shadow-ai/deploy/linux#legacy-distributions-glibc-217) | macOS and Windows have feature parity — Detect, Monitor/Protect/Enforce, and Sessions are available on both, with the same package configuration keys (see [Features](#features)). Linux is **Detect only**: deploy as native `.deb` / `.rpm` packages (cron-scheduled scans) or as a container image — see [Linux (Detect only)](/shadow-ai/deploy/linux) or [Container](/shadow-ai/deploy/container). The signed MDM package currently ships for Apple Silicon Macs and 64-bit Windows. For Intel Macs or other architectures, use the cross-platform `uv tool install runlayer` CLI path, or contact your Runlayer account team. AI Watch runs on managed-device hardware; it is not installed inside the AI assistant's containers. Outbound **HTTPS (443) to your Runlayer tenant host only** — the same hostname configured in your MDM profile (for example `runlayer.dev.company.com` or `*.runlayer.com`). Scans, hook decisions, session events, and macOS update checks all use that one endpoint, and no inbound ports are opened. If your Runlayer instance is self-hosted (including air-gapped networks), AI Watch only needs to reach that internal tenant host — no public-internet egress is required. Behind a TLS-inspection proxy, exempt the tenant hostname or install the corporate root CA in the OS trust store — see [Troubleshooting](/shadow-ai/troubleshooting). ## Package configuration Use **Settings → MDM configuration** to create an AI Watch deployment. The wizard picks your MDM, mints a single organization API key, and puts the tenant host, key, initial behavior, and platform settings into the downloaded artifacts. After deployment, select **Manage settings** on the deployment card to change `Mode`, `Sessions`, `DetectProcesses`, `DetectContainers`, `ProjectDepth`, or `ProjectTimeout`. Current macOS and Windows packages fetch these settings during the privileged hook reconcile, typically within an hour; the complete backend snapshot overrides those six values from the original profile or MSI. If a fetch fails or returns invalid data, AI Watch keeps the last valid snapshot and otherwise falls back to the MDM values. The tenant host, organization API key, identity overrides, `AutoUpdate`, CPU/memory limits, and browser-extension settings remain MDM-owned. Re-deploy the profile or MSI/registry values to change them. No behavior change requires reinstalling the package itself. The root updater installs the backend-selected binary on its own schedule; holding a version requires `AutoUpdate=false` or a matching backend rollout target. ## macOS artifacts The macOS package is a signed and notarized `.pkg` plus three MDM Configuration Profiles: | File | Purpose | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `aiwatch--macos-arm64.pkg` | Installs the `aiwatch` binary, scan LaunchAgent, hook bootstrap, and hourly root update daemon | | `com.runlayer.aiwatch.config.mobileconfig` | Tenant host, organization API key, `Mode`, legacy `Enforcement`, `Sessions`, optional process/container discovery, and default-on `AutoUpdate` | | `com.runlayer.aiwatch.pppc.mobileconfig` | Full Disk Access / TCC grants | | `com.runlayer.aiwatch.loginitems.mobileconfig` | Pre-approves bundled LaunchAgents on macOS 13+ | Deploy the three Configuration Profiles before the `.pkg` so tenant config and TCC grants are present before the first scan tick. If you need multiple configurations, deploy one `com.runlayer.aiwatch.config.mobileconfig` per group. The `.pkg`, PPPC profile, and Login Items profile are universal and can be reused unchanged across all configurations. Upload Configuration Profiles and the `.pkg` via Policy. Use Custom Attributes for tenant host and organization API key. Edit the tenant profile and deploy through Blueprints. Upload profiles and package through device groups. Deploy profiles and package through Mosyle device groups. Use any MDM with Custom App and Custom Profile support. Migrating from the legacy script-based macOS Detect rollout? Run [Legacy macOS Detect Cleanup](/shadow-ai/deploy/macos-cleanup-script-deployment) before rolling out the `.pkg`. ## Windows artifacts The Windows package is a signed MSI wrapped for Intune. The MSI writes tenant config to `HKLM\Software\Runlayer\AIWatch` **and** registers device-local Scheduled Tasks that run scans (all real user profiles) and assert hooks (SYSTEM) on a recurring schedule — no Intune Remediations required. | File | Purpose | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `aiwatch--win-x64.intunewin` | App package for Intune upload (installs `aiwatch.exe`, writes registry, registers the Scheduled Tasks) | | `custom-detection/detect-install.ps1` | Recommended Intune custom detection script (reports installed only when `aiwatch.exe` + the `AIWatchScan` task both exist) | | `scripts/bootstrap.ps1` | Optional manual user-context one-shot (SCCM / GPO logon script) | Deploy the MSI and configure capability properties — scans and hooks schedule themselves on the device. ## Linux artifacts (Detect only) The Linux deployment bundle (`aiwatch--linux-x86_64.zip`) contains a `.deb` and an `.rpm` (both named `runlayer-aiwatch`), `SHA256SUMS`, and the config templates. The package installs the `aiwatch` binary plus a cron entry that scans all users every 15 minutes. Linux is Detect-only — the device's Protect, Enforce, and Sessions features show **Disabled** in the dashboard by design. Install the `.deb` / `.rpm` via configuration management and configure the two files under `/etc/runlayer/aiwatch/`. Roll out and continuously assert the Detect-only scanner from a Salt master — package from `salt://`, config from pillar. Run the scanner as a container over bind-mounted host homes — standalone `docker run` or a Kubernetes DaemonSet / CronJob. ## Manual and custom workflows For individual test devices, use the feature pages: Install the Runlayer CLI and run `runlayer scan`. Install client hooks with `runlayer setup hooks`. Understand how device usernames map to Runlayer users. Remove package-based and legacy script-based deployments. For custom fleet integrations outside a supported MDM, use the same package configuration model: install AI Watch once, provide host and organization API key, leave Detect running, and set `Mode`, `Sessions`, and optional process/container discovery to the desired values. Omit Mode only when intentionally relying on the legacy Enforcement fallback. ## Related Resources What scans read and how discovery works Monitor, Protect, and Enforce configuration Pre-deployment, platform, and network questions Common issues and solutions