> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Watch FAQ

> Pre-deployment, security-review, and operational questions about AI Watch (Detect, Enforce, and Sessions)

Answers to the questions security, IT, and procurement teams ask most often when evaluating or rolling out AI Watch. Each answer links to the page with the full detail.

## Privacy and data handling

<AccordionGroup>
  <Accordion title="What does the scanner read on disk?">
    Detect is a metadata-first configuration scanner. For MCP servers it submits parsed configuration *metadata* — the server `command` / `args` / `url`, the client, and any project path — not your raw config files. For skills and plugins it submits metadata plus bounded artifact text (capped at 1 MB per file and 5 MB per artifact) so the backend can risk-classify the artifact. See [What the scan reads](/shadow-ai/detect#what-the-scan-reads-and-what-it-doesnt).
  </Accordion>

  <Accordion title="Can the scan be scoped or limited?">
    Yes. The crawl is confined to the signed-in user's home directory and skips high-noise and cache directories (`node_modules`, `.git`, `.venv`, caches, `Library/Application Support`, `AppData`, and more). Project-level discovery is bounded by `--project-depth` (default 7) and `--project-timeout` (default 60 seconds), and `--no-projects` skips project-level scanning entirely. See [What the scan reads](/shadow-ai/detect#what-the-scan-reads-and-what-it-doesnt).
  </Accordion>

  <Accordion title="Does it scan network shares or removable drives?">
    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. See [What the scan reads](/shadow-ai/detect#what-the-scan-reads-and-what-it-doesnt).
  </Accordion>

  <Accordion title="Does it collect file contents or just metadata?">
    MCP discoveries are metadata only. Skill and plugin discoveries include bounded file text (≤1 MB per file, ≤5 MB per artifact) needed for risk classification, deduplicated by fingerprint so the same artifact's text is not re-uploaded from every device. See [What the scan reads](/shadow-ai/detect#what-the-scan-reads-and-what-it-doesnt).
  </Accordion>
</AccordionGroup>

## Organization API key

<AccordionGroup>
  <Accordion title="What can the AI Watch organization API key do?">
    It is deliberately down-scoped. The key carries a single role — **Shadow AI Scan** (`mcp_watch_scan`) — and is accepted only on AI Watch submission endpoints: scan, skills/plugins lookup and submit, device check-in, and hooks/sessions. Used against any other API route it returns `403`. It has tenant-only identity (it is not tied to a user), cannot impersonate a user, and is blocked from policy-based access control. See [Deploy AI Watch](/shadow-ai/deploy) and [User and Identity Mapping](/shadow-ai/identity-mapping).
  </Accordion>

  <Accordion title="What is the blast radius if the key leaks?">
    Limited to AI Watch ingestion for your tenant. A leaked key can submit scan and telemetry data for your organization, but it cannot read your data back, act as a user, or reach any non-AI-Watch endpoint (those return `403`). Rotate it from **Settings → MDM Configuration** — regenerating the configuration mints a new key — and re-push the profile/MSI; the old key stops working once revoked (`401`). See [Troubleshooting → Authentication](/shadow-ai/troubleshooting#authentication-and-configuration).
  </Accordion>

  <Accordion title="How is the key stored?">
    On the device it lives in MDM-managed configuration (`OrgApiKey` in macOS managed preferences, or the `OrgApiKey` registry value under `HKLM\Software\Runlayer\AIWatch` on Windows, written by the MSI's `AIWATCH_ORG_API_KEY` install property). On the Runlayer backend it is stored only as an HMAC-SHA256 hash — the plaintext is shown once at creation and cannot be retrieved later. If it is lost, regenerate the configuration to mint a new one. See [Troubleshooting → Authentication](/shadow-ai/troubleshooting#authentication-and-configuration).
  </Accordion>

  <Accordion title="How are scans attributed to users if the key isn't tied to a user?">
    The key authenticates the tenant; user attribution comes from each device's scan context (OS username, device name), which Runlayer resolves to a user. See [User and Identity Mapping](/shadow-ai/identity-mapping).
  </Accordion>
</AccordionGroup>

## Deployment and platform

<AccordionGroup>
  <Accordion title="Is the package custom-built per organization?">
    No — the signed `.pkg` / `.msi` is identical for every customer. Your tenant host and organization API key are supplied through MDM configuration, not compiled into the binary. See [Package and platform support](/shadow-ai/deploy#package-and-platform-support).
  </Accordion>

  <Accordion title="Does it require Python or the Runlayer CLI?">
    No. The MDM package is self-contained — a single signed `aiwatch` binary with its runtime bundled, no Python or CLI prerequisite on managed devices. The `uv tool install runlayer` CLI is only for manual single-device testing. See [Package and platform support](/shadow-ai/deploy#package-and-platform-support).
  </Accordion>

  <Accordion title="Which platforms are supported?">
    Managed deployment ships for macOS (Apple Silicon / arm64) and Windows (x64). Linux is CLI-only — schedule `runlayer scan`. For Intel Macs or other architectures, use the CLI path or contact your account team. See [Package and platform support](/shadow-ai/deploy#package-and-platform-support).
  </Accordion>

  <Accordion title="What outbound access does it need?">
    Outbound HTTPS (443) to your Runlayer tenant host only — no inbound ports. Self-hosted (including air-gapped) instances only need to reach the internal tenant host. See [Package and platform support](/shadow-ai/deploy#package-and-platform-support).
  </Accordion>

  <Accordion title="Can I change configuration without reinstalling?">
    Yes. Flipping `Enforcement` / `Sessions` (and other config) only requires re-pushing the profile or MSI properties — on macOS, bump the profile's `PayloadVersion` so the MDM re-delivers it. The `.pkg` / `.msi` is reinstalled only to upgrade the AI Watch binary. See [Package configuration](/shadow-ai/deploy#package-configuration).
  </Accordion>
</AccordionGroup>

## Operation

<AccordionGroup>
  <Accordion title="Does Sessions work without Enforcement (no blocking)?">
    Yes. With `Enforcement` off (the default), hooks still forward Sessions and event telemetry whenever `Sessions` is enabled — you get full visibility without blocking. Blocking happens only when `Enforcement=true`. See [Enforce → Monitoring-only rollout](/shadow-ai/enforce#monitoring-only-rollout-no-blocking).
  </Accordion>

  <Accordion title="A skill is flagged High or Medium risk but is legitimate — what now?">
    Risk levels are a heuristic triage signal from analyzing the skill's instructions, not a malicious verdict, so legitimate skills can score High or Medium. Review the flagged instructions, bring sanctioned skills under management, and re-analyze to refresh the classification. Detect never blocks skills. See [Troubleshooting → Interpreting Discovery Results](/shadow-ai/troubleshooting#interpreting-discovery-results).
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Detect" icon="eye" href="/shadow-ai/detect">
    What scans read and how discovery works
  </Card>

  <Card title="Deploy AI Watch" icon="download" href="/shadow-ai/deploy">
    Package, platform, and configuration
  </Card>

  <Card title="Enforce" icon="shield" href="/shadow-ai/enforce">
    Blocking vs. monitoring-only
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/shadow-ai/troubleshooting">
    Auth, discovery, and package issues
  </Card>
</CardGroup>