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:
- With organisation trust, the organisation root first, so the app finds it trusted when it starts.
- 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).
- 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.
- The app.
<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.
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" /vshows the app running as the signed-in user, with nobody having opened it.%SystemRoot%\Temp\promptguard-first-start.logsays whether the install started it.
msiexec the same file (in Intune, assign the app as
Uninstall):
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.
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:
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 isco.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
.pkgas 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
.pkgwherever your MDM takes a custom package.
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-shellshows 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.loghas a PromptGuard Shadow postinstall line saying whom it started for.
"/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 barehdiutil attachcancels 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):
-Hmatters: 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.exeonce in each person’s session (an Intune PowerShell script with Run this script using the logged on credentials set to Yes). The app’s ownRunentry 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.
co.promptguard.shadow.netext.mobileconfig
co.promptguard.shadow.netext.mobileconfig
co.promptguard.shadow.network.mobileconfig
co.promptguard.shadow.network.mobileconfig
co.promptguard.shadow.netext-locked.mobileconfig
co.promptguard.shadow.netext-locked.mobileconfig
co.promptguard.shadow.loginitem.mobileconfig
co.promptguard.shadow.loginitem.mobileconfig
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/guardand/api/v1/proxy/guard/api/v1/agent/managed-policyand/api/v1/proxy/agent/managed-policy: exact match only./agentas a family stays closed; this one read-only policy poll is the exception/api/v1/enroll, and the/api/v1/exceptions,/api/v1/policiesand/api/v1/tool-requestssubtrees, so a device can file and poll its own requests/api/v1/fleet/devices,/api/v1/fleet/devices/selfand/api/v1/fleet/identity: the org’s device inventory, self-revocation, and the one row describing the caller itself./api/v1/fleet/usageis not on the list: it breaks activity down per person, which is management reporting rather than something an agent needs
/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 carryshadow_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.
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 managedengine_urllocks 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.
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.