Skip to main content
AI Watch deploys to Linux as a native package (runlayer-aiwatch .deb / .rpm) that installs the aiwatch binary and a cron entry. Every 15 minutes it scans all users on the machine for shadow AI — MCP servers, connectors/plugins, skills, and agents — and reports findings to your Runlayer tenant.

​
What you get

Linux is Detect-only:
  • Cron-scheduled shadow-AI scans across all users on the machine (root and service accounts included).
  • No hooks, no Enforce, no Sessions, and no browser extension on Linux.
  • In the dashboard, a Linux device shows Detect = Active and Enforce / Sessions = Disabled. That is the expected state, not an error.

​
Supported distributions

Packages are x86_64 and built on Ubuntu 22.04, so they require glibc 2.35 or newer:
SupportedNot supported
Ubuntu 22.04+Ubuntu 20.04
Debian 12+Debian 11
RHEL / Rocky / Alma 9+RHEL 8
Amazon Linux 2023Amazon Linux 2
Current FedoraAlpine / musl-based distros
A running cron daemon is required. The .deb depends on cron | cron-daemon | cronie and the .rpm depends on cronie, so a provider is pulled in automatically on install if missing.
Do not install AI Watch inside WSL. Windows AI Watch already scans WSL home directories from the Windows host — a WSL install creates a duplicate device in the dashboard.

​
Install

Download the aiwatch-<version>-linux-x86_64.zip deployment bundle from your Runlayer downloads access. It contains the .deb, the .rpm, SHA256SUMS, and the config templates. Contact your Runlayer account team if you don’t have the bundle yet.
1

Verify the artifacts

Packages are not GPG-signed today; SHA256SUMS is the integrity check:
sha256sum -c SHA256SUMS
2

Install the package

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

sudo dnf install -y ./runlayer-aiwatch-<version>-1.x86_64.rpm
The package installs:
PathPurpose
/usr/lib/runlayer/aiwatch/The self-contained aiwatch bundle (plus a /usr/bin/aiwatch symlink)
/usr/lib/runlayer/run-aiwatch-scan.shRoot scan wrapper — enumerates users and runs per-user scans
/etc/cron.d/runlayer-aiwatchCron entry: every 15 minutes as root
/etc/runlayer/aiwatch/config.jsonManaged config template (world-readable, non-secret)
/etc/runlayer/aiwatch/credentialsCredentials template (root-only, 0600)
Nothing executes at install time — the first scan fires on the next cron tick after you configure the two files below.

​
Configure

Configuration is two files under /etc/runlayer/aiwatch/. The split matters: per-user scan children run unprivileged and read config.json, so that file is world-readable by design — the org API key must never go in it.

​
1. /etc/runlayer/aiwatch/config.json (world-readable, non-secret)

Set Host to your tenant URL and keep Sessions and Enforcement at false — that is the Detect-only contract on Linux: 
{
  "Host": "https://tenant.runlayer.com",
  "Sessions": false,
  "Enforcement": false
}
Never put the org API key in config.json. The file is world-readable by design so unprivileged per-user scan children can read managed settings. The key belongs in the root-only credentials file below.
Optional tuning keys, with the same semantics as the macOS Configuration Profile keys (see Deploy AI Watch):
KeyDefaultPurpose
ProjectDepth7Directory depth Detect scans walk under each user home (max 20)
ProjectTimeout60Per-scan time budget in seconds (max 300)
UsernameOS usernameOverride for backend user attribution
DeviceNamehostnameOverride for the device name

​
2. /etc/runlayer/aiwatch/credentials (root-only, 0600)

Set the organization API key — the same rl_org_... key used by your macOS and Windows deployments, minted in Settings → Organization API keys with the Shadow AI Scan role: 
RUNLAYER_API_KEY=rl_org_xxxxxxxxxxxxxxxx
# Optional: override the backend host from config.json
#RUNLAYER_HOST=https://your-tenant.runlayer.com
Until RUNLAYER_API_KEY is set, the scan wrapper exits quietly without scanning — an unconfigured device produces no errors and no data.

​
How it runs

/etc/cron.d/runlayer-aiwatch runs /usr/lib/runlayer/run-aiwatch-scan.sh as root every 15 minutes (the same cadence as the macOS LaunchAgent and the Windows AIWatchScan task). The wrapper:
  • Enumerates all passwd users with an existing home directory — root and service accounts included; shared home directories are scanned once.
  • Runs aiwatch scan for each user in its own child process with privileges dropped to that user, so one user’s failure never aborts the others.
  • Skips overlapping runs via a lock file — concurrent cron ticks never queue up.
  • Routes all output to syslog, tagged runlayer-aiwatch (cron never emails root).

​
Verify

On a test machine after configuring both files: 
# 1. Trigger a full all-users scan immediately (instead of waiting for cron)
sudo /usr/lib/runlayer/run-aiwatch-scan.sh; echo $?
# Expect 0. Non-zero means at least one user's scan failed — check syslog:
journalctl -t runlayer-aiwatch --since "10 min ago"

# 2. Preview findings for your own user locally, without submitting
aiwatch scan --dry-run
Then in the Runlayer dashboard, go to Shadow AI → Devices: the device appears with OS = Linux, Detect = Active, and Enforce / Sessions = Disabled within about 15 minutes. Disabled Enforce/Sessions is the correct Detect-only state on Linux.

​
Updates

There is no auto-update on Linux. Upgrade through your configuration management (Ansible, Salt, Puppet, etc.) by installing the newer .deb / .rpm — the same install commands upgrade in place. Your edited /etc/runlayer/aiwatch/config.json and credentials files are preserved across upgrades (they are packaged as config files with noreplace semantics). Point your automation at your Runlayer downloads access to pick up the latest version.

​
Uninstall

sudo apt-get remove runlayer-aiwatch

sudo dnf remove runlayer-aiwatch
Removing the package deletes /etc/cron.d/runlayer-aiwatch immediately, so no stale schedule keeps firing. Edited config files under /etc/runlayer/aiwatch/ remain unless you purge (sudo apt-get purge runlayer-aiwatch on Debian/Ubuntu).

​
Troubleshooting

  • The wrapper exits quietly when RUNLAYER_API_KEY is missing from /etc/runlayer/aiwatch/credentials — confirm the key is set and the file is readable by root.
  • Confirm a cron daemon is running (systemctl status cron or systemctl status crond).
  • Run sudo /usr/lib/runlayer/run-aiwatch-scan.sh; echo $? and check journalctl -t runlayer-aiwatch for per-user errors.
  • Verify the device can reach your tenant host over HTTPS (443).
Either RUNLAYER_API_KEY is not configured (the unconfigured-device gate), or another scan run currently holds the lock — overlapping runs skip instead of queueing. Wait for the running scan to finish and retry.
Expected. Linux is Detect-only: there are no hooks, no Enforce, no Sessions, and no browser extension. Only macOS and Windows support those features.