Test Device

Use this flow to test package-based AI Watch or Runlayer CLI/desktop 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.

AI Watch on macOS and Windows supports 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 14+, x64 Windows, or x86_64 Linux with glibc 2.17+
Your Runlayer tenant host URL, such as https://your-instance.runlayer.com

The organization API key (Shadow AI Scan role) is generated automatically when you create the Test Device configuration below — don’t create one by hand.

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 platform tab in the setup guide. For an existing configuration, open its menu and select View deployment setup. The guide generates the commands below with your tenant host and key filled in.

Install

Install and configure

Paste this command in Terminal:

/bin/bash -c "$(curl -fsSL https://downloads.runlayer.com/install.sh)" -- --host 'https://your-instance.runlayer.com' --org-api-key 'rl_org_...'

The script resolves the signed package selected by your Client Updates policy, verifies its checksum, Runlayer Developer ID signature, and notarization, installs it, and writes the Test Device bootstrap configuration. Approve the sudo prompt when asked. If hooks are enabled, restart running AI clients after setup.

Grant Full Disk Access and verify

Without MDM, macOS cannot grant Full Disk Access automatically. Open the settings page and reveal the binary:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
open -R /usr/local/lib/runlayer/aiwatch/aiwatch

Add the revealed binary to Full Disk Access and enable it. macOS 13 and newer may show a one-time Background Item Added notification; no action is required.

/usr/local/bin/aiwatch scan

# Protect, Enforce, or Sessions only
sudo /usr/local/bin/aiwatch setup hooks check --mdm

In Runlayer, open Shadow AI → Devices and confirm the test Mac appears.

Install and configure

Paste this command in PowerShell:

& ([ScriptBlock]::Create((irm https://downloads.runlayer.com/install.ps1))) `
  -RunlayerHost 'https://your-instance.runlayer.com' `
  -OrgApiKey 'rl_org_...'

The script resolves the x64 MSI selected by your Client Updates policy, verifies its SHA-256 checksum, and starts Windows Installer with a progress dialog. Approve the UAC prompt. The install succeeds only when Windows Installer returns 0 or 3010 (restart required).

Verify

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 AI → Devices and confirm the Windows device appears. If hooks are enabled, restart running AI clients after installation.

Install and configure

Paste this command in a terminal:

/bin/bash -c "$(curl -fsSL https://downloads.runlayer.com/install.sh)" -- --host 'https://your-instance.runlayer.com' --org-api-key 'rl_org_...'

The script detects Debian or RPM packaging and the host’s glibc version, resolves and verifies the compatible x86_64 package, installs it, and writes the tenant host and root-only credentials. It selects the standard package for glibc 2.35+ and the glibc2.17 variant for glibc 2.17–2.34. Do not install AI Watch inside WSL; the Windows package already scans WSL homes.

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 AI → Devices and confirm the Linux device appears with Detect = Active and Protect / Enforce / Sessions = Disabled. That disabled state is expected.

Install and configure

Choose Runlayer CLI → Test Device in the deployment wizard, then paste:

/bin/bash -c "$(curl -fsSL https://downloads.runlayer.com/install.sh)" -- --host 'https://your-instance.runlayer.com' --org-api-key 'rl_org_...' --package cli

The script resolves, verifies, installs, and configures the signed macOS package selected by your Client Updates policy.

Approve Login Items and verify

Without MDM, macOS cannot pre-approve Login Items. If prompted, allow Runlayer under System Settings → General → Login Items:

open "x-apple.systempreferences:com.apple.LoginItems-Settings.extension"
defaults read /Library/Preferences/com.runlayer.cli
/usr/local/bin/runlayer --version
launchctl print "gui/$(id -u)/com.runlayer.cli.schedule"

Skill sync runs after approval or the next login.

Install and configure

Choose Runlayer CLI → Test Device in the deployment wizard, then paste this command in PowerShell:

& ([ScriptBlock]::Create((irm https://downloads.runlayer.com/install.ps1))) `
  -RunlayerHost 'https://your-instance.runlayer.com' `
  -OrgApiKey 'rl_org_...' `
  -Package cli

The script resolves the x64 CLI MSI selected by your Client Updates policy, verifies its SHA-256 checksum, and starts Windows Installer with a progress dialog. Approve the UAC prompt. The install succeeds only when Windows Installer returns 0 or 3010 (restart required).The one-command flow requires CLI version 0.30.7 or newer. If your Client Updates policy selects an older version, the script stops with an error; use the manual fallback below instead.

Verify

Get-ItemProperty "HKLM:\Software\Runlayer\CLI"
Get-ScheduledTask -TaskPath "\Runlayer\" | Format-Table TaskName, State
Start-ScheduledTask -TaskPath "\Runlayer\" -TaskName "CLISchedule"
runlayer --version

Skill sync runs on the CLISchedule scheduled task; the kickstart above triggers the first sync immediately.

Install and configure

Choose Runlayer CLI → Test Device in the deployment wizard, then paste this command in a terminal:

/bin/bash -c "$(curl -fsSL https://downloads.runlayer.com/install.sh)" -- --host 'https://your-instance.runlayer.com' --org-api-key 'rl_org_...' --package cli

The script detects Debian or RPM packaging and the host’s glibc version, resolves and verifies the compatible x86_64 package, installs it, writes the tenant host and root-only credentials, then best-effort triggers the first Client Updates policy check.

Verify

runlayer --version
sudo /usr/lib/runlayer/run-cli-schedule.sh
sudo /usr/lib/runlayer/run-cli-update.sh
grep runlayer /etc/cron.d/runlayer-cli

Cron runs skill sync at minute 23 and the managed update check at minute 41 of every hour. The commands above trigger both immediately.

The bootstrap scripts are public, but target resolution and every package download require your tenant host and organization API key. They do not send the key to downloads.runlayer.com.

An MDM profile overrides local Test Device configuration. On macOS, Managed Preferences under /Library/Managed Preferences take precedence over the local /Library/Preferences domain.

Manual installation fallback

Use these steps if the hosted bootstrap script cannot run. Download the resolved installer from the Test Device setup guide first.

macOS AI Watch

For package version 0.29.15 or newer:

sudo installer -pkg 'aiwatch-<version>-macos-arm64.pkg' -target /
sudo /usr/local/bin/aiwatch setup config \
  --host 'https://your-instance.runlayer.com' \
  --org-api-key 'rl_org_...'

Versions before 0.29.15 do not include aiwatch setup config, so the one-command installer stops and sends you here. Install the package, write the local preference domain, and kickstart hooks when enabled:

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

PREFS="/Library/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"

# Protect, Enforce, or Sessions only
sudo launchctl kickstart -k system/com.runlayer.aiwatch.bootstrap

Windows AI Watch

Run from the MSI download directory:

$process = Start-Process msiexec.exe -ArgumentList @(
  '/i'
  '"aiwatch-<version>-win-x64.msi"'
  '/qb!'
  'AIWATCH_HOST=https://your-instance.runlayer.com'
  'AIWATCH_ORG_API_KEY=rl_org_...'
) -Wait -PassThru
if ($process.ExitCode -notin @(0, 3010)) {
  throw "Windows Installer failed with exit code $($process.ExitCode)"
}

The MSI writes bootstrap configuration under HKLM\Software\Runlayer\AIWatch and registers AIWatchScan, AIWatchHooks, and AIWatchUpdate under \Runlayer.

Linux AI Watch

The one-command installer automatically selects the standard package for glibc 2.35+ or the glibc2.17 variant for glibc 2.17–2.34. For a manual install, the standard packages below require glibc 2.35 or newer; older distributions need a tagged artifact and the legacy install commands.Install the standard package for your distribution:

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

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

Write the world-readable host configuration and separate root-only key:

sudo install -d -m 755 /etc/runlayer/aiwatch
sudo tee /etc/runlayer/aiwatch/config.json >/dev/null <<'JSON'
{
  "Host": "https://your-instance.runlayer.com"
}
JSON
sudo chmod 644 /etc/runlayer/aiwatch/config.json

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

Never put the organization API key in config.json; it is world-readable by design. See the full Linux guide for supported distributions, updates, and troubleshooting.

macOS CLI/desktop

For package version 0.29.15 or newer:

sudo installer -pkg 'runlayer-<version>-macos-arm64.pkg' -target /
sudo /usr/local/bin/runlayer setup config \
  --host 'https://your-instance.runlayer.com' \
  --org-api-key 'rl_org_...'
sudo launchctl kickstart system/com.runlayer.cli.update

For an older package:

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

PREFS="/Library/Preferences/com.runlayer.cli"
sudo defaults write "$PREFS" Host -string "https://your-instance.runlayer.com"
sudo defaults write "$PREFS" OrgApiKey -string "rl_org_..."
sudo chown root:wheel "$PREFS.plist"
sudo chmod 644 "$PREFS.plist"
sudo launchctl kickstart -k "gui/$(stat -f %u /dev/console)/com.runlayer.cli.schedule"
sudo launchctl kickstart system/com.runlayer.cli.update

The final launchctl kickstart fires the first update check immediately, so the device converges on the Client Updates policy target instead of waiting for the hourly com.runlayer.cli.update schedule.

Windows CLI/desktop

For CLI version 0.30.7 or newer, run from the MSI download directory:

$process = Start-Process msiexec.exe -ArgumentList @(
  '/i'
  '"runlayer-<version>-win-x64.msi"'
  '/qb!'
  'CLI_HOST=https://your-instance.runlayer.com'
  'CLI_ORG_API_KEY=rl_org_...'
) -Wait -PassThru
if ($process.ExitCode -notin @(0, 3010)) {
  throw "Windows Installer failed with exit code $($process.ExitCode)"
}

The MSI writes bootstrap configuration under HKLM\Software\Runlayer\CLI and registers the CLIUpdate and CLISchedule scheduled tasks under \Runlayer. CLIUpdate is locked to SYSTEM and Administrators, so a non-elevated session cannot start it after the MSI UAC prompt. The task’s first check runs as SYSTEM about two minutes after registration, then hourly, so the device converges on the Client Updates policy target without a parent-session kick.MSIs before 0.30.7 ignore the CLI_HOST / CLI_ORG_API_KEY properties. Install without them, then write the registry values from an elevated prompt:

reg add "HKLM\Software\Runlayer\CLI" /v Host /t REG_SZ /d "https://your-instance.runlayer.com" /f
reg add "HKLM\Software\Runlayer\CLI" /v OrgApiKey /t REG_SZ /d "rl_org_..." /f
Start-ScheduledTask -TaskPath "\Runlayer\" -TaskName "CLIUpdate"

Those older MSIs delay the first CLIUpdate check by about an hour. The elevated prompt can start the task immediately; 0.30.7 and newer do not need that kick.

Linux CLI/desktop

The one-command installer automatically selects the standard package for glibc 2.35+ or the glibc2.17 variant for glibc 2.17–2.34. For a manual install, the standard packages below require glibc 2.35 or newer.Install the standard package for your distribution:

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

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

For CLI version 0.30.8 or newer, write the shared host configuration and root-only key with:

sudo /usr/bin/runlayer setup config \
  --host 'https://your-instance.runlayer.com' \
  --org-api-key 'rl_org_...'
sudo /usr/lib/runlayer/run-cli-update.sh

setup config preserves local non-policy settings, writes config.json as 0644, and keeps the organization key only in the 0600 credentials file. The explicit wrapper command triggers the first Client Updates policy check; cron repeats it hourly.For an older package, write the same files manually:

sudo install -d -m 755 /etc/runlayer/aiwatch
sudo tee /etc/runlayer/aiwatch/config.json >/dev/null <<'JSON'
{
  "Host": "https://your-instance.runlayer.com"
}
JSON
sudo chmod 644 /etc/runlayer/aiwatch/config.json
sudo tee /etc/runlayer/aiwatch/credentials >/dev/null <<'EOF'
RUNLAYER_API_KEY=rl_org_...
EOF
sudo chmod 600 /etc/runlayer/aiwatch/credentials

Never put the organization API key in config.json; it is world-readable by design. Existing installs need one package upgrade to 0.30.8 or newer before the hourly full-CLI updater exists.

The verification below applies to macOS AI Watch installs (scripted or manual). For Windows and Linux, use the verify steps in their tabs above.

Verification

On a test Mac after installation and configuration:

# 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. 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 AI → 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.mobileconfig (which carries the Login Items payload) is scoped to the same device group as the .pkg, then force an MDM sync and check:

sfltool dumpbtm | grep -i runlayer

Expect the Runlayer item to show enabled allowed visible.

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

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

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.

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.

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Prerequisites

Install

Manual installation fallback

Verification

Common post-deploy issues

Customize scan schedule (optional)

Upgrade

Uninstall

Troubleshooting

​Prerequisites

​Install

​Manual installation fallback

​Verification

​Common post-deploy issues

​Customize scan schedule (optional)

​Upgrade

​Uninstall

​Troubleshooting

Prerequisites

Install

Manual installation fallback

Verification

Common post-deploy issues

Customize scan schedule (optional)

Upgrade

Uninstall

Troubleshooting