Docs/Shadow Ai/Deployment

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 ANTS Platform, 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-ap-…) and a secret key (sk-ap-…), sent as the headers:

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

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, notarized .pkg (universal — Apple Silicon and Intel) that installs Endpoint Security (ES) and Network Extension (NE) system extensions. Requires macOS 13 (Ventura) or later, ~250 MB free disk space.

Permissions

ActionNeeds admin?
Install the .pkgYes — the installer writes to /Applications and runs its setup step as root
Day-to-day runningNo — the agent runs in the logged-in user's own session; standard (non-admin) accounts are fully supported
Version upgrades (self-serve)Yes — re-running the signed installer needs administrator approval, same as initial install
ℹ

Fleet rollout needs zero end-user interaction. Managed (MDM) deployments upgrade silently with no end-user action, and can pre-approve every permission below via configuration profile.

Install

Download AntsAgent.pkg from Settings → Deployment & Keys → Desktop agent, open it, and complete the installer (admin approval required).

Grant permissions

The logged-in user approves three permissions in System Settings → Privacy & Security — all three are required for the agent to start observing:

PermissionRequired?If withheld
AccessibilityYesOnboarding blocks; menu bar shows "Grant Accessibility"
Full Disk AccessYesOnboarding blocks until granted
System extension approval (Endpoint Security + Network Extension)YesThe extensions never reach a running state, so nothing is observed

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 and pre-approve every permission above with configuration profiles — no end-user clicks needed:

ProfilePurpose
pppc-accessibility.mobileconfigPre-grants Accessibility
system-extension-policy.mobileconfigPre-approves the Endpoint Security + Network Extension system extensions
content-filter.mobileconfigActivates the Network Extension in content-filter mode

Keys are delivered via a managed-preferences profile at /Library/Managed Preferences/ai.agenticants.agent.plist:

KeyValue
orgPublicKeyYour project's public key (pk-ap-…) — required
orgSecretKeyYour project's secret key (sk-ap-…) — required (both keys must be set together)
apiHostOptional override; defaults to the platform's API host

In-product Settings → Deployment & Keys generates all of the above, pre-filled with your project's real keys.

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 ANTS Platform 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.

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

© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026