Docs
Shadow AI
Deploying Agents & Extensions

Deploying Agents & Extensions

Shadow AI collects signals from lightweight clients you deploy to your workforce's machines:

ClientPlatformsDiscovers
Browser extensionChrome, Edge, FirefoxWeb AI tools (ChatGPT, Claude.ai, Gemini, Copilot, …)
Desktop agentmacOS, WindowsDesktop AI apps, CLI tools, AI network activity, file events
Coding-agent telemetryany OSClaude Code, Codex CLI, GitHub Copilot usage via OpenTelemetry

All clients authenticate with the same project keys and attribute activity to the same users and devices. You can deploy any combination.

Everything below lives under Shadow AI → Settings → Deployment & Keys in AgenticAnts, which renders the exact download links, copy-paste MDM payloads, and commands for your project (pre-filled with your keys). This page explains the concepts and the rollout path.

Prerequisites

  • You're an Organization Owner or AI Steward (required to manage deployment and keys).
  • For MDM rollout: admin access to your MDM (Jamf, Intune, Kandji), Group Policy, or browser-management console.

Project keys

Every client authenticates to your project with a public key (pk-…) and a secret key (sk-…), sent as the headers:

X-Shadow-Ai-Public-Key: pk-...
X-Shadow-Ai-Secret-Key: sk-...

There is one key pair per project, shared by all platforms. Manage them under Settings → Deployment & Keys:

  • Reveal — generates the pair on first use and shows the secret (shown in full only once).
  • Graceful rotation — issues a new pair while the old one stays valid for 7 days, so clients re-enroll without disruption. Use this for routine rotation.
  • Immediate rotation — issues a new pair and revokes the old one at once. Every client gets 401 until it picks up the new keys.
  • Revoke all — emergency kill-switch; stops all collection until new keys are deployed.
⚠️

Treat the secret key like a password. Put it in your MDM's secure policy payloads — don't paste it into shared documents or tickets. Rotate on a schedule per your security policy.

The enrollment script ("Step 0")

The fastest path — especially for managed fleets — is the enrollment script. It's a single script (one for macOS, one for Windows) that seeds your project keys and the device/user identity into the OS so that every client (agent and browser extensions) enrolls silently on first launch — no per-user sign-in.

What it does:

  • Reads basic device identity (hostname, OS version, hardware serial) and user identity (username, full name, email; optionally department / job title if present in the local directory).
  • Writes your project keys + identity into managed-preference locations the agent and each browser read on startup.
  • Is idempotent — safe to re-run. A matching uninstall script is also provided.

Download the script

Go to Settings → Deployment & Keys, choose macOS or Windows, and download the enrollment script (and optionally the uninstall script). It comes pre-filled with your project keys.

Run it

  • Self-serve / pilot: run it once on the machine (macOS: chmod +x then run; it prompts for sudo once to seed system-level browser policies).
  • Fleet: push it through your MDM as a run-as-logged-in-user script (see MDM recipes in-product).

Install the clients

Install the desktop agent and/or browser extensions. On launch they read the seeded keys and enroll automatically.

With the enrollment script in place, clients enroll without any user interaction. If you skip it, browser-extension users can still self-enroll interactively (the extension turns green once connected), and the desktop agent installer can carry keys directly when deployed via MDM.

Desktop agent

The desktop agent discovers desktop AI apps, CLI tools, AI network flows, and file events. It is code-signed and notarized.

macOS — a Developer-ID-signed .pkg that installs Endpoint Security (ES) and Network Extension (NE) system extensions.

Install

Download AntsAgent.pkg from Settings → Deployment & Keys → Desktop agent, open it, and complete the installer.

Grant permissions

macOS requires the user to approve the agent in System Settings:

  • Accessibility
  • Full Disk Access
  • Approve the agent's system extensions (Endpoint Security + Network Extension) when prompted.

Verify

The device appears under Shadow AI → Devices as Healthy once it checks in. The Settings → Overview page tracks permission coverage across your fleet.

MDM (Jamf / Intune / Kandji): distribute the .pkg, pre-approve the system extensions and permissions via a configuration profile (PPPC / system-extension allowlist), and inject keys via a managed-preferences profile or the enrollment script. In-product Settings → Deployment & Keys renders the exact profile payloads.

Browser extensions

The browser extension discovers web AI tools. It captures only typed usage metadata (host, path, file metadata) — never page content or request/response bodies. See Data & Privacy.

Chrome — installed from the Chrome Web Store (Manifest V3).

  • Self-serve: Add to Chrome from the store, pin the icon, and confirm enrollment (icon turns green).

  • MDM / managed Chrome: push two policies —

    • ExtensionInstallForcelist to force-install the extension, and
    • the 3rdparty extension policy to inject your project keys.

    These map onto macOS (.plist), Linux (JSON), Windows registry (HKLM\Software\Policies\Google\Chrome), and Intune. In-product Settings → Deployment & Keys generates the exact payload for each channel.

MDM force-installed extensions update silently. Self-serve installs may show a permission-change prompt on auto-update — prefer the managed path for fleet deployment.

Coding-agent telemetry

Claude Code, OpenAI Codex CLI, and GitHub Copilot can stream OpenTelemetry directly to AgenticAnts using your project keys — no agent install required. This is the easiest way to capture terminal and IDE coding-assistant usage.

See the dedicated guide: Coding Agent Telemetry (OTel Collector).

Recommended rollout

Pilot

Deploy to a handful of devices via self-serve or a manual run of the enrollment script. Confirm they show Healthy under Devices.

Stage via MDM

Wrap the enrollment script + installers + force-install policies in your MDM. Push to one pilot device first before the fleet.

Roll out

Deploy to the fleet. Watch Settings → Overview for enrollment, online count, MDM coverage, and (macOS) permission coverage.

Govern

Once data is flowing, classify tools under AI Tools, Registry & Policy and enrich identities with Directory Integration.

Next steps

QuickstartDirectory Integration