Docs/Shadow Ai/Deployment

Deploying Agents & Extensions

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

Client	Platforms	Discovers
Browser extension	Chrome, Edge, Firefox 140 or later	Web AI tools in the Tool Registry
Desktop agent	macOS 13 or later; Windows 10 22H2 or later and Windows 11	Desktop AI apps, command-line AI tools, files used in AI apps, MCP servers (macOS), AI network traffic (macOS)
Coding-agent telemetry	Any OS	Claude Code, GitHub Copilot CLI and OpenAI Codex CLI usage through OpenTelemetry

Safari is not supported. All clients attribute activity to the same users and devices. You can deploy any combination.

ℹ

All of the steps below live under Settings > Deployment & Keys. That page generates the download links, enrollment scripts and MDM payloads for your project, filled in with your credentials. This page explains the concepts and the rollout path.

ℹ

The clients observe and report. In Warn mode the browser extension also shows a banner when someone opens an Unsanctioned AI tool. The clients do not block AI tools.

Prerequisites

Access to Settings > Deployment & Keys in the project. Viewing, rotating and revoking keys requires write access to Discover AI settings, which project owners have.
For fleet rollout: admin access to your MDM (Jamf, Intune, Kandji), Group Policy, or browser management console.

Step 1: Choose an authentication method

The Authentication method card on Deployment & Keys offers two options:

Method	How it works
API keys	Every device uses the project's shared key pair. Simple, but a single device cannot be revoked on its own.
Device certificates (mTLS)	Each device gets its own certificate during enrollment. Any single device can be revoked.

API keys are the default. Device certificate authentication is supported and is turned on per project with this setting. When it is on, each device registers with a fleet credential from the enrollment script or MDM profile and then authenticates with its own certificate.

Project keys

With API keys, every client authenticates with a public key (pk-ap-...) and a secret key (sk-ap-...). There is one key pair per project, shared by all platforms. Manage it under Deployment & Keys > Keys & credentials:

Graceful rotation: issues a new pair. The old pair keeps working for 7 days so devices can re-enroll without disruption.
Immediate rotation: issues a new pair and revokes the old one at once. Every device gets 401 until it re-enrolls.
Revoke all credentials: disables every key. No data comes in until you issue new keys.

⚠

Treat the secret key like a password. Deliver it through your MDM's managed payloads, not shared documents or tickets.

Step 2: Enroll devices

The enrollment script (one for macOS, one for Windows) prepares a device so the desktop agent and browser extensions connect on their own, with no user sign-in. Download it from Deployment & Keys > Enroll devices, pre-filled for your project.

The script:

Records the device identity (hardware ID, serial number, hostname, OS version) and user identity (username, full name, email, and directory attributes where available) in managed settings that the agent and each browser read.
Writes your project credentials into the managed settings that the desktop agent and the Chrome, Edge and Firefox extensions read.
Applies your collector settings (see below).
Configures coding-agent telemetry for Claude Code, GitHub Copilot CLI and Codex CLI when it finds them.
Can be re-run safely. A matching unenroll script is available.

⚠

The browser extension needs the enrollment script. The extension uploads events only when the device identity has been written by the enrollment script. Without it, a self-serve install can sign in but does not send usage events.

Download the script and run it once: in Terminal on macOS, or in PowerShell as administrator on Windows. Then install the clients.

Collector settings

In the Enroll devices step you can switch off individual desktop agent collectors for the project. Examples: Time spent in AI apps, Files used in AI apps, Prompt counts, Clipboard (macOS), Network activity (macOS), Coding tool usage data, and the per-app log readers for Claude Code, Cursor, GitHub Copilot CLI, VS Code Copilot Chat, Codex CLI, Gemini CLI, the Claude desktop app and Aider. The process monitor that detects AI tools cannot be switched off.

Collector settings are pushed from the console. A collector you switch off stops on each device at the desktop agent's next check-in, about every hour. There is nothing to reinstall, and you do not need to re-run the enrollment script or update the MDM profile.

The enrollment script and the MDM profile also write the list into managed settings, so a newly enrolled device starts with the right collectors before its first check-in:

macOS: the disabledCollectors key in the ai.agenticants.agent managed preferences domain, written by the enrollment script or by the MDM profile that Deployment & Keys generates.
Windows: the DisabledCollectors value under HKLM\SOFTWARE\Policies\AntsAgent, written by the enrollment script.

Older agent versions ignore this setting.

Step 3: Install clients

Desktop agent

The desktop agent detects the desktop apps and command-line tools in the Tool Registry. It records:

Which AI apps and command-line tools run, and how long AI apps are in the foreground.
For command-line AI tools: the executable path, the command-line arguments and the working folder. Text passed as a command-line argument is included.
Prompt counts, token counts, tool-call counts and the model, read from the local session files of supported tools: Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Cursor, Aider, and on macOS also Continue, the llm CLI and Zed. Prompt text is not sent.
Prompt counts for desktop chat apps, from the composer's send button on Windows (Claude, Microsoft Copilot, Notion) or from the length of the input text on macOS. The text itself is never read.
Files used in AI apps: file name, path, size and type.
macOS only: MCP servers configured or called in Claude Code, Claude Desktop, GitHub Copilot CLI and Gemini CLI (server name, call count, connection status), and AI network traffic (see below). The Windows agent counts MCP tool calls from the Claude desktop app's log but does not report MCP server names.

macOS: a Developer ID signed and notarized .pkg, universal for Apple Silicon and Intel. Requires macOS 13 (Ventura) or later. It installs an Endpoint Security system extension and a Network Extension.

Action	Needs admin?
Install the `.pkg`	Yes
Day-to-day running	No. The agent runs in the logged-in user's session; standard accounts are supported.

Self-serve install

Install

Run the enrollment script, then download AntsAgent.pkg from Deployment & Keys > Desktop agent and run the installer.

Grant permissions

Approve these in System Settings > Privacy & Security:

Accessibility
Full Disk Access
Endpoint Security system extension
Network Extension

Verify

The menu bar icon turns green when connected, and the device appears under Discover AI > Devices.

MDM (Jamf, Intune, Kandji)

Upload AntsAgent.pkg to your MDM and assign it. It installs silently.
Add the keys profile from Deployment & Keys. It is a managed preferences payload for the domain ai.agenticants.agent with orgPublicKey, orgSecretKey, apiHost and, if set, disabledCollectors. With device certificates, the profile carries a fleetEnrollmentCredential instead of the keys.
Pre-approve permissions with the two configuration profiles ANTS provides for the macOS agent: a PPPC profile (Accessibility, Full Disk Access) and a system extension profile (Endpoint Security and Network Extension approval, and the content filter). With both profiles in place, users see no permission prompts.

AI network traffic. The Network Extension runs as a content filter that always allows traffic. For network hosts listed in the registry for a tool (currently Cursor, Windsurf, GitHub Copilot, Claude, Gemini and Perplexity), it counts connections and bytes sent and received. ANTS stores these per device and host. The stored record does not include which process made the connection. Traffic to other hosts is not recorded.

Browser extension

The browser extension discovers web AI tools in the Tool Registry. It refreshes its copy of the registry about every 10 minutes. It records usage metadata: page URL and title, the AI tool, prompt submission events, model name where the request exposes it, and file uploads as file name, size and type. It does not record prompt or response text. See Data & Privacy.

Chrome: installed from the Chrome Web Store (Manifest V3). Store builds update automatically.

Self-serve: run the enrollment script, add the extension from the store and pin the icon. It connects on its own and the icon turns green.
Managed: force-install the extension and pass it your credentials with the 3rdparty extension policy. Deployment & Keys generates the payload for each channel:
- macOS: custom settings profile for com.google.Chrome (ExtensionSettings with force_installed)
- Linux: managed policy JSON in /etc/opt/chrome/policies/managed
- Windows: Group Policy registry (ExtensionInstallForcelist under HKLM\SOFTWARE\Policies\Google\Chrome)
- Intune: settings catalog

To check a managed install, open chrome://extensions, edge://extensions or about:addons. The extension should show "Installed by your administrator".

Disable private browsing

The extension usually does not run in private windows, so private browsing is a way around it. When you generate the Chrome or Edge policy payloads under Install clients, turn on Disable private browsing to add the browser's own policy for it: IncognitoModeAvailability set to 1 for Chrome, or InPrivateModeAvailability set to 1 for Edge. It is off by default.

Extension removal

A force-installed extension cannot be removed or disabled by a managed user. When the extension is removed, for example on a device where it was installed self-serve, the browser opens an ANTS page that records the removal and raises an Extension removed alert. See Tamper and silence alerts.

Device status

Each device appears under Discover AI > Devices with its installed clients, agent version, owner, last check-in and health:

Health	Meaning
Healthy	Checked in recently with no problems.
Degraded	Online, with an issue such as repeated upload failures, a large retry queue, or missing macOS permissions.
Offline	No check-in for more than 70 minutes. Clients check in about every hour.

Settings > Discover AI shows fleet coverage: client counts, how many are online, desktop agents under MDM, macOS permission coverage, and devices that need attention.

To be alerted when a device stops reporting, the extension is removed or an agent is unenrolled, turn on tamper and silence alerts.

Coding-agent telemetry

Claude Code, GitHub Copilot CLI and OpenAI Codex CLI can send OpenTelemetry data to ANTS Platform. The enrollment script configures this automatically when it finds these tools. Content capture is off by default and is turned on per tool under Deployment & Keys > Coding-agent telemetry.

See Coding-Agent Telemetry.

Recommended rollout

Pilot

Enroll a few devices with the enrollment script and install the clients. Confirm they show Healthy under Devices.

Stage through MDM

Package the enrollment script, installers and force-install policies in your MDM. Push to one pilot device first.

Roll out

Deploy to the fleet. Watch the coverage summary under Settings > Discover AI.

Classify

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