Skip to main content
Detect scans devices for installed AI clients, MCP server configurations, skill artifacts, client-native agent definitions, and plugin artifacts. It is the always-on AI Watch feature: deploy AI Watch once, and Detect scans run from the package configuration. See User and Identity Mapping for how device usernames are attributed to Runlayer users, and Interpreting Discovery Results for how to verify a discovery.

​
How It Works

  1. Client and Artifact Discovery: The Runlayer CLI checks known installation signals, MCP configuration files, skill artifacts, client-native agent definitions, and installed plugin artifacts
  2. Secure Submission: Client presence, configuration, skill, agent-definition, and plugin data is securely submitted to Runlayer
  3. Classification: Runlayer classifies each discovery:
    • AI Clients are classified as:
      • Managed: Approved through your organization’s client allowlist
      • Shadow: Detected but not yet approved (flagged for review)
      • Risk: Client presence uses a Low baseline risk; review its device, user, version, and detection evidence for context
    • MCP Servers are classified as:
      • Managed: Running through Runlayer (approved and monitored)
      • Shadow: Configured outside Runlayer (flagged for review)
    • Skills are classified as:
      • Managed: Published and managed through Runlayer
      • Shadow: Installed outside organizational control (flagged for review)
      • Outdated: Previously managed but now out of date
    • Skill Risk Levels: Each discovered skill is assigned a risk level:
      • High: Skill contains risky instructions (prompt injection, data exfiltration patterns)
      • Medium: Skill has potentially risky characteristics that warrant review
      • Low: Skill has minor concerns but is unlikely to pose a threat
      • Minimal: Skill appears safe with no concerning patterns detected
  4. Alerting: Administrators and security teams are notified of newly discovered shadow clients, servers, skills, and plugins

​
Security Team Workflow

  • Get visibility into supported AI clients, MCP servers, skills, and plugins across your organization
  • Identify which AI tools employees are using, even when no MCP server is configured
  • Build an inventory of shadow clients, integrations, and skills for risk assessment
  • Track trends in AI client, MCP, and skill adoption over time
When shadow MCP servers are discovered, evaluate:
  • Source: Is the MCP from a known vendor or unknown source?
  • Permissions: What data and systems can it access?
  • User context: Who configured it and for what purpose?
  • Network exposure: Does it connect to external endpoints?
When shadow skills are discovered, evaluate:
  • Risk level: Is the skill flagged as High or Medium risk?
  • Instructions: Does the skill contain prompts that could manipulate AI behavior?
  • Source: Is the skill from a trusted repository or an unknown source?
  • Scope: What actions does the skill instruct the AI to perform?
Based on risk assessment:
  • Low risk: Migrate to Runlayer-managed server or skill for visibility
  • Medium risk: Require user to submit for approval review
  • High risk: Immediate remediation via MDM policy or direct intervention
  • Risky: Incident response, credential rotation, forensic analysis

​
AI Client Detection

Detect inventories a supported AI client independently of its configured artifacts. A client can therefore appear in the Shadow Overview even when it has zero MCP servers, skills, or plugins. Depending on the operating system and client, installation signals include:
  • macOS: app bundles in /Applications or ~/Applications
  • Windows: uninstall-registry entries or known installation paths
  • Linux: binaries in known executable paths or desktop files
  • All platforms: known configuration or state paths
  • Docker containers: client artifacts discovered inside a running container
  • Artifact evidence: a discovered MCP server, skill, agent definition, plugin, or extension also confirms that its client is present
Each Client row includes the available version and detection methods: app, cli, registry, container, config, server, skill, plugin, or extension. New clients default to Shadow. From the Shadow Overview, administrators can add an approved client to the organization allowlist, marking it Managed and removing it from the shadow inventory.

​
Supported Clients

For each OS, the tables below list the clients whose MCP, skill, and plugin artifacts Detect scans. Detect also reports the client itself when it finds an installation signal. A — means the client has no concept of that artifact type, so there is nothing to scan; see What — means below.

​
macOS

​
Windows

​
Linux

​
Presence-only clients

Detect also inventories these clients from installation signals, although MCP configuration, skill, and plugin scanning is not yet supported for them: Kiro, Trae, Qoder, Void, Aider, Amp, Crush, Droid, Qwen Code, OpenHands, Auggie, Grok CLI, and Hermes. Presence depends on an applicable signal on the device’s operating system. For example, OpenHands on Windows is detected through WSL.

​
What — means

A — indicates the client has no equivalent of that artifact type, so there is nothing for Detect to scan — it is not a gap in Detect coverage.
  • No skills convention (Gemini CLI, Antigravity): these clients do not define a SKILL.md directory layout. MCP servers and, where applicable, plugins/extensions are still scanned.
  • No plugin marketplace (VS Code, Claude Desktop, Windsurf, Goose, Zed, Cline, Antigravity, Warp): these clients do not have a separate plugin/extension format that bundles MCP servers, so there is no plugin layer beyond the MCP server config itself. For Goose and Zed, extensions are the MCP server and are surfaced through the MCP Servers column.
  • Warp MCP servers are scanned from two sources: the ~/.warp/.mcp.json config file and Warp’s warp.sqlite database (servers added through Warp’s in-app gallery, stored in the mcp_server_installations table). Both feed the MCP Servers column; servers present in both are counted once.

​
Shadow Skills Discovery

Detect discovers skill artifacts alongside MCP server configurations in the same scan. Each discovered skill is classified and assigned a risk level based on its content.

​
Skill Classification

​
Risk Levels

Skills flagged as High or Medium risk warrant immediate attention from security teams.

​
Shadow Plugins Discovery

Detect also discovers installed plugin artifacts alongside MCP servers and skills. Discovered plugins are classified using the same managed/shadow model: Plugin discoveries appear in the Shadow dashboard alongside MCP server and skill data. Re-analysis also covers plugins — reclassifying them when catalog data changes.

​
Agent Definition Discovery

Detect inventories client-native agent definitions for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, OpenCode, and Goose. User-level and project-level definitions are deduplicated by content hash while each device, path, client, and container location remains visible as a separate sighting. Definition contents are parsed locally; Runlayer receives only bounded metadata and the content hash.

​
Run Detect

TLS trust: The runlayer CLI and MDM-deployed aiwatch binary verify HTTPS through the OS trust store — macOS Keychain (login + System), Windows certificate stores (Current User + Local Machine), and the Linux distro CA bundle (/etc/ssl/certs). Corporate root CAs pushed via MDM, GPO, or Intune are honored automatically with no extra config. If your corporate root is not installed system-wide and scans fail with CERTIFICATE_VERIFY_FAILED, see Troubleshooting for --ca-bundle, RUNLAYER_CA_BUNDLE, SSL_CERT_FILE, and REQUESTS_CA_BUNDLE overrides.
For managed fleets, use Deploy AI Watch. Detect is always enabled in the AI Watch package; the MDM Configuration wizard controls only the optional Enforce and Sessions features. This page keeps manual testing on the Runlayer CLI path.

​
Manual installation

For testing, one-off verification, or custom workflows, install the CLI and run a scan directly. Step 1 — Install the Runlayer CLI:
Restart your terminal after installing so ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows) is on PATH. Step 2 — Verify the CLI is on PATH:
If you see command not found, restart your terminal or run uv tool update-shell. See Troubleshooting for more details. Step 3 — Authenticate: You can authenticate interactively or with an organization API key.
Opens a browser for authentication. Credentials are stored in your OS keychain when available, with a fallback to ~/.runlayer/config.yaml.
Scans submitted with interactive login credentials will not be associated with any of the configuration cards on the Settings → MDM Configuration page. Use an organization API key (Option B) if you need scan data linked to a specific configuration.
Step 4 — Run a scan:
The scan discovers installed AI clients, MCP server configurations, skill artifacts, agent definitions, and installed plugin artifacts in a single pass. When container detection is enabled, the same artifact classes are scanned inside running Docker containers.

​
Custom scan scheduling

Use these modular components when you need custom scheduling outside the managed AI Watch package. Install the CLI as a tool (if not already installed):
Example: Cron Job (macOS/Linux)
Example: Task Scheduler (Windows)

​
What the scan reads (and what it doesn’t)

Security and privacy reviewers usually want to know exactly what touches disk during a scan. Detect is a metadata-first configuration scanner, not a content crawler. Where it looks
  • The crawl is confined to the signed-in user’s home directory ($HOME on macOS/Linux, %USERPROFILE% on Windows). It does not walk system directories or other users’ homes.
  • Project-level discovery walks home to a bounded depth — default --project-depth 7, with a --project-timeout ceiling of 60 seconds. Pass --no-projects to skip project-level scanning entirely and only read the known global client config paths.
  • A cooperative in-process governor keeps the scan’s resource footprint within soft caps (--cpu-cores / --max-cpu-percent throttle CPU, --memory-limit-mb aborts the scan if its Python heap exceeds the ceiling). Defaults are generous, so a normal scan is unaffected; tighten them on constrained hosts. See the tuning table for the MDM keys.
  • High-noise and cache directories are skipped: node_modules, .git, venv / .venv, __pycache__, dist, build, target, vendor, Library/Caches, Library/Application Support, AppData, .Trash, tmp, .cache, .npm, .yarn, and plugin-install caches.
  • Symlinks are not followed out of the home tree. On Windows, the SYSTEM all-users scan additionally drops reparse points and verifies each hit’s real path stays inside the profile.
What it submits
  • AI clients: the normalized client identifier, display name, version when available, detection methods, and matched configuration or state paths
  • MCP servers: parsed configuration metadata only — the server command / args / url, the client name, and any project path where the config was found. Raw config files are not uploaded.
  • Skills and plugins: metadata plus bounded artifact text so the backend can risk-classify the skill or plugin. Text collection is capped at 1 MB per file and 5 MB per artifact; oversized files are skipped. Artifacts are deduplicated by fingerprint — once an artifact’s fingerprint is already known, later devices submit only the per-device installation record, not the file text again.
  • Agent definitions: parsed name and description, client, scope, redacted path, project path, and content hash. Raw definition content is not uploaded.
Scope is defined by the home-directory boundary, not by a drive-type filter. Paths outside the home directory are never traversed, so a network share or removable drive mounted elsewhere on the system is not crawled — but there is no separate exclusion that skips a drive mounted under the home directory.

​
Viewing Results

After a scan, view discovered clients, servers, skills, agent definitions, and plugins in the Runlayer dashboard:
  1. Navigate to Shadow
  2. In Overview, use the Type filter to select Client. Each row identifies the client, user, and device. Open a row to review available versions and detection methods, or add the client to your organization’s allowlist.
  3. The Shadow MCP section shows:
    • Total devices scanned
    • Managed vs. shadow servers
    • Newly discovered shadow servers
  4. The Shadow Skills section shows:
    • Shadow skills by risk level (High, Medium, Low, Minimal)
    • Skill classification breakdown (Shadow, Managed, Outdated)
    • Top repositories with shadow skills
    • Skill discovery trends over time
  5. The Shadow Plugins section shows:
    • Managed vs. shadow plugins
    • Plugin classification breakdown

​
User Attribution

Detect resolves device usernames to Runlayer users so discoveries appear under the right owner. Some usernames remain unresolved because of shared machines, contractor naming, directory gaps, or ambiguous matches. See User and Identity Mapping for the full resolution flow and the Settings → MDM Configuration → Unresolved usernames workflow.

Enforce

Block shadow MCP tool calls in real-time

Deploy AI Watch

Install the package and configure Enforce / Sessions

User and Identity Mapping

Resolve device usernames to Runlayer users

Responding to Discoveries

Security team response framework

Re-analyzing Classifications

Refresh server and skill classifications after changes

Troubleshooting

Common issues and solutions

FAQ

Pre-deployment, security-review, and operational questions