Test Device

Use this flow to test package-based AI Watch on one device without enrolling it in an MDM. A single Test Device configuration and organization API key can report from macOS, Windows, and Linux.

macOS and Windows support Monitor, Protect, Enforce, and Sessions. Linux is Detect only and ignores the configuration’s endpoint Mode and Sessions settings. For a managed rollout, use Deploy AI Watch.

Prerequisites

Local administrator or root access to the test device
A supported package platform: Apple Silicon macOS, x64 Windows, or x86_64 Linux
An organization API key with the Shadow AI Scan role, created in Settings → Organization API keys
Your Runlayer tenant host URL (for example, https://your-instance.runlayer.com)

Record the organization API key when the configuration is created. Runlayer only shows the full secret once. If the Test Device guide later shows <YOUR_API_KEY> and you no longer have the secret, delete the configuration and create a new one.

Create the configuration under Settings → MDM configuration → Add new → Test Device, then select the operating-system tab in the setup guide. For an existing configuration, open its menu and select View deployment setup.

macOS — install and configure

Download the signed package

On the macOS tab, download the signed aiwatch-<version>-macos-arm64.pkg selected by your Client Updates policy.

Install the package

From the directory containing the download, run:

sudo installer -pkg "aiwatch-<version>-macos-arm64.pkg" -target /

The package installs /usr/local/bin/aiwatch, the scan LaunchAgent, the hook bootstrap LaunchDaemon, and the hourly update LaunchDaemon.

Write the managed preferences

Replace the host and organization API key below. Set Mode, its paired legacy Enforcement value, Sessions, and the discovery and scan-tuning values (DetectProcesses, DetectContainers, ProjectDepth, ProjectTimeout) to match the Test Device configuration:

PREFS="/Library/Managed Preferences/com.runlayer.aiwatch"

sudo defaults write "$PREFS" Host -string "https://your-instance.runlayer.com"
sudo defaults write "$PREFS" OrgApiKey -string "rl_org_..."
sudo defaults write "$PREFS" Mode -string "monitor"
sudo defaults write "$PREFS" Enforcement -bool false
sudo defaults write "$PREFS" Sessions -bool false
sudo defaults write "$PREFS" DetectProcesses -bool false
sudo defaults write "$PREFS" DetectContainers -bool false
sudo defaults write "$PREFS" ProjectDepth -int 7
sudo defaults write "$PREFS" ProjectTimeout -int 60
sudo chown root:wheel "$PREFS.plist"
sudo chmod 644 "$PREFS.plist"

Pair Mode and legacy Enforcement as follows. See Endpoint modes for the behavior of each mode.

Mode	`Enforcement`
`monitor`	`false`
`protect`	`true`
`enforce`	`true`

Set Sessions to true to collect session data, or false to disable it. Monitor with Sessions disabled is scan-only and does not install hooks.Set DetectProcesses, DetectContainers, ProjectDepth, and ProjectTimeout to match the Test Device configuration’s discovery and scan-tuning settings; the values shown in the in-app setup guide already reflect them.

Grant Full Disk Access

Without MDM, there is no PPPC profile to grant Full Disk Access automatically. Open System Settings → Privacy & Security → Full Disk Access, select +, press Command-Shift-G, and add:

/usr/local/lib/runlayer/aiwatch/aiwatch

Enable the entry before scanning. Without this permission, macOS can prevent AI Watch from reading project configurations under protected locations such as ~/Desktop, ~/Documents, and ~/Downloads.macOS 13 and newer may also show a one-time Background Item Added notification because no MDM Login Items profile pre-approves the scan LaunchAgent.

Apply hooks when enabled

If Mode is Protect or Enforce, or Sessions is enabled, run:

sudo launchctl kickstart -k system/com.runlayer.aiwatch.bootstrap

Restart your AI clients after the bootstrap completes so they load the installed hook configurations. Skip this step for scan-only Monitor (Mode=monitor, Sessions=false).

Verification

On a test Mac after installation and configuration:

# 1. .pkg installed (binary + scan agent + bootstrap + updater)?
test -x /usr/local/bin/aiwatch && \
  test -f /Library/LaunchAgents/com.runlayer.aiwatch.plist && \
  test -f /Library/LaunchDaemons/com.runlayer.aiwatch.bootstrap.plist && \
  test -f /Library/LaunchDaemons/com.runlayer.aiwatch.update.plist && \
  echo "binary + scan 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 preferences configured (host + org API key + Mode / Enforcement / Sessions)?
defaults read /Library/Managed\ Preferences/com.runlayer.aiwatch.plist

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

# 5. Hourly update daemon loaded in the system domain?
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 → Devices and confirm the test Mac appears.

Common post-deploy issues

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.loginitems.mobileconfig is scoped to the same device group as the .pkg, then force an MDM sync and check:

sfltool dumpbtm | grep -i runlayer

On macOS 13+, expect the Runlayer item to show enabled allowed visible. macOS 12 and older ignore the Login Items payload; the notification control only exists on macOS 13+.

Gatekeeper blocks the package

Verify you are deploying the official signed and notarized release artifact:

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.

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:

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. 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:

#!/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

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

By default, the root com.runlayer.aiwatch.update LaunchDaemon checks hourly and installs the backend-selected signed + notarized .pkg. An MDM Custom App push or another manual installer run remains a fallback, but the next hourly tick will restore the backend-selected target. To hold a manually pushed version, set AutoUpdate=false in managed preferences or align the backend rollout policy first. The package preinstall removes only the previous /usr/local/lib/runlayer/aiwatch/ onedir tree before PackageKit deploys the new payload, so obsolete modules and version metadata cannot survive an upgrade or rollback. The separate Runlayer CLI installation is preserved. Mid-scan upgrades are safe — macOS lets you unlink an open file, and the running aiwatch keeps its mapped pages until the next LaunchAgent tick picks up the new version. Postinstall intentionally leaves an already-loaded updater running so it cannot terminate its own installer transaction; the hourly cadence remains stable. MDM Configuration Profiles are unchanged across version upgrades. Preferences written manually under com.runlayer.aiwatch also remain in place.

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.

Troubleshooting

For deployment diagnostics and common macOS package issues, see Troubleshooting.

Windows — install and configure

Windows testing uses the same signed x64 MSI as an Intune deployment, but installs it directly on one device.

Download the signed MSI

On the Windows tab of the Test Device setup guide, download aiwatch-<version>-win-x64.msi.

Install with the generated configuration

Open PowerShell as Administrator in the download directory and run the command rendered by the setup guide. It includes the selected host, organization API key, Mode, Sessions, discovery, scan-tuning, and update settings:

msiexec /i aiwatch-<version>-win-x64.msi /qn AIWATCH_HOST=https://your-instance.runlayer.com AIWATCH_ORG_API_KEY=rl_org_... AIWATCH_MODE=monitor AIWATCH_ENFORCEMENT=0 AIWATCH_SESSIONS=0 AIWATCH_DETECT_PROCESSES=0 AIWATCH_DETECT_CONTAINERS=0 AIWATCH_AUTO_UPDATE=1 AIWATCH_PROJECT_DEPTH=7 AIWATCH_PROJECT_TIMEOUT=60

The MSI installs aiwatch.exe, writes configuration under HKLM\Software\Runlayer\AIWatch, and registers the AIWatchScan, AIWatchHooks, and AIWatchUpdate tasks under \Runlayer.

Restart AI clients when hooks are enabled

If Mode is Protect or Enforce, or Sessions is enabled, restart running AI clients after installation so they load their hook configurations. The hook task is a no-op for scan-only Monitor (Mode=monitor, Sessions=false).

Verify

In an elevated PowerShell window:

Get-ItemProperty "HKLM:\Software\Runlayer\AIWatch"
Get-ScheduledTask -TaskPath "\Runlayer\" | Format-Table TaskName, State
Start-ScheduledTask -TaskPath "\Runlayer\" -TaskName "AIWatchScan"

# Protect, Enforce, or Sessions only
& "C:\Program Files\Runlayer\AIWatch\aiwatch.exe" setup hooks check --mdm

In Runlayer, open Shadow → Devices and confirm the Windows device appears. See Intune verification for detailed task and log checks.

Linux — install and configure (Detect only)

Linux packages run all-user scans every 15 minutes through cron. They do not install hooks or support endpoint modes or Sessions. See Linux support before installing; do not install inside WSL.

Download a package

On the Linux tab of the Test Device setup guide, download the x86_64 package for the distribution:

.deb for Debian or Ubuntu
.rpm for RHEL, Rocky, Alma, Fedora, or Amazon Linux

Install

sudo apt-get install -y ./runlayer-aiwatch_<version>_amd64.deb

sudo dnf install -y ./runlayer-aiwatch-<version>-1.x86_64.rpm

Write the non-secret Detect configuration

Keep the organization API key out of this world-readable file:

sudo install -d -m 755 /etc/runlayer/aiwatch
sudo tee /etc/runlayer/aiwatch/config.json >/dev/null <<'JSON'
{
  "Host": "https://your-instance.runlayer.com",
  "Sessions": false,
  "Enforcement": false,
  "DetectProcesses": false,
  "DetectContainers": false,
  "ProjectDepth": 7,
  "ProjectTimeout": 60,
  "AutoUpdate": true
}
JSON
sudo chown root:root /etc/runlayer/aiwatch/config.json
sudo chmod 644 /etc/runlayer/aiwatch/config.json

Write the root-only credentials

sudo tee /etc/runlayer/aiwatch/credentials >/dev/null <<'EOF'
RUNLAYER_API_KEY=rl_org_...
EOF
sudo chown root:root /etc/runlayer/aiwatch/credentials
sudo chmod 600 /etc/runlayer/aiwatch/credentials

Scan and verify

sudo /usr/lib/runlayer/run-aiwatch-scan.sh
aiwatch scan --dry-run
grep run-aiwatch /etc/cron.d/runlayer-aiwatch

In Runlayer, open Shadow → Devices and confirm the Linux device appears with Detect = Active and Protect / Enforce / Sessions = Disabled. That disabled state is expected. See the full Linux guide for legacy distributions, updates, and troubleshooting.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Prerequisites

macOS — install and configure

Verification

Common post-deploy issues

Customize scan schedule (optional)

Upgrade

Uninstall

Troubleshooting

Windows — install and configure

Linux — install and configure (Detect only)

​Prerequisites

​macOS — install and configure

​Verification

​Common post-deploy issues

​Customize scan schedule (optional)

​Upgrade

​Uninstall

​Troubleshooting

​Windows — install and configure

​Linux — install and configure (Detect only)

Prerequisites

macOS — install and configure

Verification

Common post-deploy issues

Customize scan schedule (optional)

Upgrade

Uninstall

Troubleshooting

Windows — install and configure

Linux — install and configure (Detect only)