Skip to main content
Fleet enrollment is how an admin deploys Shadow AI across many employees at once. Instead of handing out a shared API key, each device redeems a one-time token for its own least-privilege credential, so you can attribute activity per employee and revoke any single device instantly, without touching the rest. Prefer to watch? This page as a silent, step-by-step video:

Two ways in, and they attribute differently

The member signs in

The person opens Connect this device in the app, approves it in their own browser session, and the device binds to their membership of your organization. The dashboard shows their account, not a label. Any member can do this for their own machine, they do not need to be an admin, and no admin has to mint anything.

An admin mints a token

For bulk rollout and MDM, where nobody is at the keyboard to click anything. The device gets the same scan-only credential and the same protection, but it binds to no account, the dashboard marks it unverified and shows only the free-text label the enrollment supplied.
Both are supported and neither is going away. If you need to know who a device belongs to, for per-seat accounting, or to answer “whose laptop is this?”, use the sign-in flow. Devices enrolled before this existed keep working and show as unverified; there is no need to re-enroll them, and re-enrolling is the only way to convert one.Joining an organization always requires an invitation. There is no email-domain auto-join: sharing a mail domain with your organization does not put someone in it, so a contractor or an acquired-company account cannot enroll into your fleet by signing up with a work address.

Roll it out

1

Create an enrollment token

In the dashboard, open Shadow AI and click Create a rollout token (MDM) (or Add a device for a single machine). These buttons mint tokens for any platform with a set lifetime and use count; to pin a platform or choose the use count and expiry, mint one with POST /dashboard/fleet/enrollment-tokens. The token is shown once: copy it then. Copy config copies it as the enrolment_token setting for macOS, Windows or Linux, ready to put in place on a device.
2

Each device redeems it

Push the token to your devices as the enrolment_token key of the managed configuration, along with the app, settings first. The app starts by itself once installed, and on that first launch a device with no credential redeems it with no browser sign-in, and the token is never shown in the app. The device receives a scan-only credential bound to your organization’s fleet, no shared secret, no per-employee account needed.
3

Each person trusts the certificate once

The first time protection turns on, the operating system asks the person to trust the device’s own inspection certificate: their Mac password, or a Windows security warning. MDM can’t approve it ahead of time, because each device creates its own. Tell people to expect this one prompt, and that it names PromptGuard. On a Mac, the network extension and its proxy configuration can be pre-approved by MDM profiles, so macOS asks nothing else.
4

Activity rolls up to you

Every verdict is tagged with the device and surface (desktop / browser). Admins see the whole fleet’s AI activity in one place; employees never see each other’s data.
5

Revoke any device in one click

Shadow AI → Enrolled devices → Revoke. That device’s credential is deactivated immediately and its next request is rejected, the rest of the fleet is unaffected.

Push the app

An MDM installs an app and launches nothing, so the installers start it. The Windows .msi and the macOS .pkg start the app straight away for whoever is signed in, and at every login for every user. The app then enrolls from the enrolment_token and turns protection on with nobody opening it. A person who was not signed in at install time gets it at their next login. Releases up to 0.10.8 do neither: see Releases up to 0.10.8. Deploy in this order:
  1. With organisation trust, the organisation root first, so the app finds it trusted when it starts.
  2. The managed configuration, with the enrollment token. The app starts the moment it is installed, and one that starts before its token arrives may not enroll until it next starts (the next login).
  3. On a Mac, the approval profiles. If the app arrives first, macOS holds the extension as waiting for approval, and the profile completes it when it arrives, so this order is a preference, not a requirement.
  4. The app.
Replace <version> below with the release you deploy; the download links always serve the latest.

Windows

Deploy the .msi (https://api.promptguard.co/public/download/shadow/windows-msi). It installs for every user, in C:\Program Files\PromptGuard Shadow. The .exe installs only for the account that runs it, in that account’s %LOCALAPPDATA%, so pushed from an RMM running as SYSTEM it lands in SYSTEM’s profile, where nobody uses it.
Add INSTALLDIR="D:\Apps\PromptGuard Shadow" to install somewhere else. Exit code 0 means it installed. In Intune: Apps → Windows → Add → Line-of-business app, upload the .msi and assign it as Required to the group that reaches your PCs (see Which Intune group to assign to). The msiexec install and removal commands were run on release 0.10.6 in a clean Windows 11 machine. The .msi writes the machine Run value (HKLM\Software\Microsoft\Windows\CurrentVersion\Run, PromptGuard Shadow) that starts the app at every user’s login. It also starts the app at once in every signed-in session, as that person and not elevated, through a scheduled task (PromptGuard Shadow first start, with no trigger of its own). Nothing asks the person anything. To check one PC:
  • reg query "HKLM\Software\Microsoft\Windows\CurrentVersion\Run" /v "PromptGuard Shadow" shows "C:\Program Files\PromptGuard Shadow\pgshadow-shell.exe" --launched-at-login.
  • tasklist /fi "imagename eq pgshadow-shell.exe" /v shows the app running as the signed-in user, with nobody having opened it.
  • %SystemRoot%\Temp\promptguard-first-start.log says whether the install started it.
To remove it, give msiexec the same file (in Intune, assign the app as Uninstall):
Run pgshadow.exe uninstall as the signed-in user first: an uninstall run as SYSTEM cannot reach that user’s proxy setting or certificate. Uninstall says why, and what it leaves behind. The Run value and the first-start task go with the .msi. For one person’s own PC, the .exe installs and uninstalls silently with /S: PromptGuard.Shadow_<version>_x64-setup.exe /S, then "%LOCALAPPDATA%\PromptGuard Shadow\uninstall.exe" /S.

Enrolling a Windows PC in Intune

How a PC is enrolled decides which Intune group can reach it:
  • Microsoft Entra join, hybrid join or Windows Autopilot gives the PC a Microsoft Entra device, which a device group can hold. Automatic Intune enrollment on join needs Microsoft Entra ID P1 (included in Microsoft 365 Business Premium and E3/E5, not in Intune Plan 1 on its own).
  • Enroll only in device management (Settings > Accounts > Access work or school) gives the PC no Microsoft Entra device. Its Intune page shows Registered in Microsoft Entra: Unknown, and no device group can ever hold it.
Windows finds Intune from two DNS records on the domain in the person’s sign-in name: enterpriseenrollment.<domain> (a CNAME to enterpriseenrollment-s.manage.microsoft.com) and enterpriseregistration.<domain> (a CNAME to enterpriseregistration.windows.net). If the domain doesn’t publish them, Enroll only in device management says We couldn’t auto-discover a management endpoint matching the username entered and asks for an MDM server URL. Enter:
then sign in as before. Adding the two DNS records saves everyone typing it; Entra join and Autopilot never ask for it.

Which Intune group to assign to

Assign the organization root, the app and the managed configuration to the same kind of group, so all three reach the same PCs: A device group never reaches a PC enrolled with Enroll only in device management, because the PC can’t join it: the app and its settings sit assigned and never arrive. A user group does reach it. Intune applies a Required app, an imported administrative template and a trusted certificate profile to every PC that user enrolled, and they still apply machine-wide. Tested on a Windows 11 PC enrolled this way: the .msi and the managed configuration, assigned to the enrolling user’s group, arrived within minutes of a Sync. A user group follows the person: every PC they enroll gets Shadow AI, and a PC they didn’t enroll gets nothing, whoever signs in to it. On a PC enrolled with Enroll only in device management, Edge installs the browser extension your policy forces, but Chrome ignores a forced install from outside the Chrome Web Store unless the PC is joined to Microsoft Entra ID or Active Directory.

macOS

Deploy the .pkg (https://api.promptguard.co/public/download/shadow/macos-pkg), PromptGuard.Shadow_<version>_universal.pkg (0.10.9 and later), as it is. It installs the notarized app, the same app as the release .dmg, in /Applications (macOS refuses to activate a system extension from an app anywhere else), and a LaunchAgent, /Library/LaunchAgents/co.promptguard.shadow.login.plist, that starts the app at every login for every user. Its postinstall then starts the app for whoever is signed in; on an upgrade it stops the old copy first. The package itself is not signed with a Developer ID Installer certificate: an MDM installs it as root, which needs no signature, but a person double-clicking it is refused. Set updater_enabled to off on Macs you deploy the package to, and deliver each release by uploading its .pkg. The package installs the app owned by root, so the app cannot update itself without an administrator’s password, and with the updater on it would ask the person for one. Do not deploy the .dmg: a disk image cannot carry the LaunchAgent or the postinstall, so an app your MDM copies in from it never starts until someone opens it. For 0.10.8 and earlier, which have no .pkg, see Releases up to 0.10.8.
  • Intune: Apps → macOS → Add → macOS app (PKG). Upload the .pkg. Leave the pre-install and post-install scripts empty: the package carries its own. Check that the included app’s bundle ID is co.promptguard.shadow, and leave Ignore app version off, so a newer build you upload replaces the old one. Assign it as Required to a device group. Use macOS app (PKG), not Line-of-business app, which takes only a package signed with a Developer ID Installer certificate, and not macOS app (DMG).
  • Jamf Pro: Settings → Computer management → Packages → New, upload the .pkg as it is, and add it to a Policy (trigger Recurring Check-in, frequency Once per computer) scoped to the computers.
  • Kandji, Mosyle and other MDMs: upload the same .pkg wherever your MDM takes a custom package.
Optionally, also push the login item profile: without it the app still starts at every login, but macOS 13 and later shows “Background Items Added” and lets the person switch it off in System Settings → General → Login Items. The LaunchAgent starts the app at every login even for someone who turned protection off (with user_controls: full): the app then sits in the menu bar with protection off, as that person left it. To check one Mac:
  • pgrep -lx pgshadow-shell shows the app running for the signed-in user, with nobody having opened it.
  • launchctl print "gui/$(id -u)/co.promptguard.shadow.login" shows the agent loaded.
  • /var/log/install.log has a PromptGuard Shadow postinstall line saying whom it started for.
To remove it: unassigning the app leaves it installed, because neither Intune nor Jamf removes a package. Remove it with a script run as root: run "/Applications/PromptGuard Shadow.app/Contents/MacOS/pgshadow" uninstall as the signed-in user first (it reverses what the agent set up in their account), quit the app, delete /Applications/PromptGuard Shadow.app and /Library/LaunchAgents/co.promptguard.shadow.login.plist, and run pkgutil --forget co.promptguard.shadow. Unassign the profiles too, the locked profile first.

Releases up to 0.10.8

Up to 0.10.8 nothing starts the app after an MDM install. The app registered its own login launch the first time someone opened it, so a device nobody opened never enrolled and never protected anything, at any later login either. Those releases also have no .pkg, and their .dmg asks for agreement to a license when it is mounted, which makes Intune fail with “Failed to mount DMG”. Update to a later release when you can. Until then:
  • Mac, the app. Wrap the app in a package once per release, on any Mac, and deploy that as above:
    yes | accepts the license agreement a bare hdiutil attach cancels on.
  • Mac, the first start. An MDM shell script, run as root once per device after the app is installed (Intune: Devices → macOS → Shell scripts, Run script as signed-in user No, 3 retries):
    -H matters: without it the app starts with root’s home folder, cannot write its settings, and protects nothing. After that first start, the app’s own login item covers later logins for that user, once protection is on.
  • Windows, the first start. Run C:\Program Files\PromptGuard Shadow\pgshadow-shell.exe once in each person’s session (an Intune PowerShell script with Run this script using the logged on credentials set to Yes). The app’s own Run entry covers later logins, once protection is on.

Approve the Network Extension (macOS)

macOS asks the person to allow the agent’s Network Extension, and then its network configuration, unless your MDM approves both first. Push these as custom profiles, scoped to computers (Intune: device channel). macOS accepts them only from an MDM the Mac is enrolled in with Automated Device Enrollment or user-approved MDM, never from a double-clicked file. Jamf’s System Extensions payload and Intune’s Extensions template take the first row’s values directly. The network configuration has two keys Apple’s reference marks optional that macOS refuses the profile without, so upload the file below rather than building it by hand. No Privacy Preferences (PPPC) profile is needed. After these, the only prompt left is the certificate trust in step 3.
To check one Mac: systemextensionsctl list shows co.promptguard.shadow.netext as [activated enabled], and sudo profiles show -type configuration lists the profiles. Removing the Network Extension profile deactivates the extension; remove the locked profile first.

Why per-device credentials

Least privilege

Device credentials can only scan: even if one leaked, it can’t reach management or proxy endpoints.

Attribution, honestly labelled

A device the member signed in to enroll names their account. One enrolled from an admin token carries a free-text label instead, and the dashboard says unverified rather than presenting a guess as an identity.

Scoped visibility

Fleet activity is visible to your org’s admins only, never through a shared key.
The device credential is an ordinary PromptGuard API key presented as X-API-Key, marked scan-only. What it may reach is generated from the two mount prefixes the guard router is served under (/api/v1 and /api/v1/proxy, the second because the Python SDK defaults its base URL there), so the same handler is reachable by both names:
  • /api/v1/guard and /api/v1/proxy/guard
  • /api/v1/agent/managed-policy and /api/v1/proxy/agent/managed-policy: exact match only. /agent as a family stays closed; this one read-only policy poll is the exception
  • /api/v1/enroll, and the /api/v1/exceptions, /api/v1/policies and /api/v1/tool-requests subtrees, so a device can file and poll its own requests
  • /api/v1/fleet/devices, /api/v1/fleet/devices/self and /api/v1/fleet/identity: the org’s device inventory, self-revocation, and the one row describing the caller itself. /api/v1/fleet/usage is not on the list: it breaks activity down per person, which is management reporting rather than something an agent needs
A trailing slash cannot change the outcome: paths are compared with it stripped, so /api/v1/guard/ now 404s for everyone rather than 403-ing only scan-only keys. Anything not on that list fails closed with 403 scope_denied.

Org-managed updates

On a Shadow plan (Shadow Team or Shadow Enterprise, the plans that carry shadow_fleet_management; a gateway plan does not), admins control how the agents on enrolled devices update:
  • Force the update mode: e.g. require Automatic so every device stays current, regardless of what the user picks locally.
  • Pin the release channel: keep the fleet on stable, or move a test group to the beta channel.
  • Set a minimum version: devices below the floor are forced to update. Until they do, they keep protecting with their current policy (a stale agent never disarms), but coverage-reducing controls are locked.
On a managed device, the corresponding controls in the app’s Settings show “Managed by your organization” and can’t be changed by the user. Everything else about the app behaves the same.

Managed configuration (MDM)

Prefer to watch? Pushing these settings with Intune, on Macs and on Windows PCs, as silent, step-by-step videos:
Some settings belong to the organization rather than to the person at the keyboard. The agent reads those from the operating system’s own management channel, the one your MDM already uses, before it talks to anyone: The key names are identical in all three: Two things follow from where those values live:
  • Managed configuration wins, and it locks. Precedence is managed → a command-line flag → an environment variable → the user’s own ~/.promptguard/config.json → the default. Every key you supply is locked: the app shows it as set by your organization and the person on the device can’t change it. A managed engine_url locks the dashboard the device enrolls against along with it.
  • A bad value is reported, never guessed at. A source that exists but can’t be read or parsed contributes nothing and is shown as a problem in the app. An unknown key name, a blank value or the wrong type is ignored and reported the same way. A value of the right type that doesn’t parse, triage_setting: "hybird": still wins its key and resolves to that key’s safe default rather than falling through to a lower source.
If you pushed an MDM artifact before this release, push a fresh one. The artifacts the dashboard generated used older key names (base_url, enrollment_token) and, on Windows, a PromptGuard\Shadow subkey, none of which the agent reads, so those pushes configured nothing. Artifacts downloaded now carry the keys in the table above. The stale keys stay on the device, ignored but locked, until the profile or policy that set them is replaced.

Device liveness

The device table shows Last seen: the last time that device’s agent checked in with PromptGuard. The agent checks in on its own schedule (roughly every six hours, and once at launch) whether or not anyone on that machine is using AI, so this tracks whether the agent is still running, not how busy the person is. Two readings worth telling apart:
  • never: the device redeemed its enrollment token but has never checked in since. Usually the agent was never actually installed, or it is installed and not running. Enrolling is not the same as being protected.
  • A stale timestamp: the agent checked in and then stopped. Expect the machine to be off, offline, or to have had the agent quit or uninstalled.
Revoking a device disables its credential, so a revoked device stops checking in and its Last seen freezes at the moment it last reached us.

For automation

If you’re scripting enrollment or building tooling, these are the endpoints behind the dashboard: See the API Reference for full request and response schemas.

Next steps

Choose where your data runs

Keep the engine in our cloud, on your own infrastructure, or fully air-gapped.
Last modified on November 16, 2026