Skip to main content

​
Common Authentication Errors

Detect scans use organization API keys (created in Settings → API Keys with the Detect Scan role). Auto-provisioning (hooks, sync) uses enrollment keys (created in Settings → Enrollment Keys).
HTTP StatusErrorCauseResolution
401Missing/invalid API keyKey is incorrect, revoked, or missingVerify the organization API key (Detect) or enrollment key (auto-provisioning) in your script
403ForbiddenAPI key lacks required roleEnsure the org key has the Detect Scan role
500Server errorInternal server issueContact Runlayer support

​
Common Issues

Quick fixes:
  1. Check script permissions: chmod +x run-ai-watch-macos.sh
  2. Verify the script is assigned to the correct device group in your MDM
  3. Check MDM console for script execution errors
  4. Review logs at /var/log/ai-watch.log
Quick fixes:
  1. Ensure PowerShell execution policy allows the script
  2. Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser if needed
  3. Verify the script is assigned to the correct device group in your MDM
  4. Review logs at %ProgramData%\AIWatch\ai-watch.log
Quick fixes:
  1. Check script logs for errors (see Log Locations below)
  2. Verify the API key is active and not revoked — org API key in Settings > API Keys (Detect) or enrollment key in Settings > Enrollment Keys (auto-provisioning)
  3. Confirm network connectivity from devices to your Runlayer host
  4. Check that the script is actually being executed by your MDM
  5. Verify the Runlayer API is reachable from device networks
Quick fixes:
  1. Check that uv is properly installed and in the system PATH
  2. Review verbose output with uvx runlayer scan --verbose
  3. Ensure no firewall rules are blocking the Runlayer API
  4. Verify the organization API key has the Detect Scan role
Symptoms: Scan completes successfully but doesn’t find MCP servers you know exist in directories like Desktop, Documents, or Application Support.Cause: macOS TCC (Transparency, Consent, and Control) is blocking access to protected directories.Resolution:
  1. Deploy the PPPC profile to grant Full Disk Access to the wrapper binary
  2. Ensure devices are enrolled via User-Approved MDM or Automated Device Enrollment
  3. Verify the profile is installed: profiles show -type configuration | grep runlayer
  4. Verify the wrapper binary is installed and signed correctly: 
    ls -la /usr/local/bin/runlayer-scan
codesign -dv /usr/local/bin/runlayer-scan
  5. Re-run the scan after the PPPC profile is applied
Quick fixes:
  1. Check LaunchAgent logs: cat /tmp/runlayer-scan.stderr.log
  2. Verify the LaunchAgent is loaded: launchctl list | grep runlayer
  3. Check the main log: cat /var/log/ai-watch.log
  4. Verify the wrapper binary exists and is signed: 
    ls -la /usr/local/bin/runlayer-scan
codesign -dv /usr/local/bin/runlayer-scan
  5. Test the wrapper binary: /usr/local/bin/runlayer-scan --dry-run
  6. Try manually triggering: launchctl kickstart -kp gui/$(id -u)/com.runlayer.scan
Cause: The script detected that the LaunchAgent may not have transitioned to a running state after being triggered. This can happen due to timing issues or if the LaunchAgent failed to start.Quick fixes:
  1. Check if the scan actually ran by reviewing the logs: 
    cat /tmp/runlayer-scan.stdout.log
cat /tmp/runlayer-scan.stderr.log
  2. Verify the LaunchAgent is properly loaded: launchctl list | grep runlayer
  3. Check system load — high CPU usage can delay process startup
  4. Manually trigger the scan to test: launchctl kickstart -kp gui/$(id -u)/com.runlayer.scan
  5. If the issue persists, check Console.app for launchd errors related to com.runlayer.scan

​
Log Locations

PlatformLog Location
macOS/var/log/ai-watch.log
macOS LaunchAgent/tmp/runlayer-scan.stdout.log, /tmp/runlayer-scan.stderr.log
Windows%ProgramData%\AIWatch\ai-watch.log
Windows (Intune)C:\ProgramData\Microsoft\IntuneManagementExtension\Logs

​
Exit Codes

CodeMeaning
0Success
1General failure (no user logged in, missing config)
2Network failure
3Installation failure

​
Verifying PPPC Profile Deployment (macOS)

After deploying the PPPC profile, verify it’s installed on target devices: 
# List installed configuration profiles
profiles show -type configuration | grep -i runlayer

# Check if Full Disk Access is granted (requires admin)
sudo sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
  "SELECT client, auth_value FROM access WHERE service='kTCCServiceSystemPolicyAllFiles';"

​
Verifying Wrapper Binary (macOS)

Verify the wrapper binary is properly installed and signed: 
# Check wrapper binary is installed
ls -la /usr/local/bin/runlayer-scan

# Verify the signature and identifier
codesign -dv /usr/local/bin/runlayer-scan

# Test the wrapper binary (dry run)
/usr/local/bin/runlayer-scan --dry-run
The signature should show Identifier=com.runlayer.scan which matches the PPPC profile.

​
Getting Help

If you continue to experience issues:
  1. Collect the relevant log files from the affected device
  2. Note the HTTP status codes and error messages
  3. Contact Runlayer support with the collected information