Install
Install the app for your platform, open it, choose Connect this device and then Turn on protection. On a Mac, macOS asks you once to allow the network extension in System Settings and once to trust the inspection certificate. For scripted installs see Command line.Full quickstart
Step-by-step: prerequisites, the menu-bar option, verifying, your first block,
and uninstall.
What it protects
The agent works from a host allowlist of known AI vendors, it decrypts and inspects traffic to those hosts and leaves everything else undecrypted. The list covers:
Being on the list is not the same as being captured on every operating system:
which tools each platform’s capture route actually reaches is on
Supported AI tools.
The list is compiled into the agent, so adding a vendor means a new agent
release (which reaches your devices through Updates), see
Known Limitations for how to
request one.
For scripted or MDM deployments, stable download URLs redirect (302) to the
latest artifact:
What happens at send-time
Every prompt or upload to a monitored AI tool gets one verdict:- Block: secrets, API keys, and prompt-injection attempts are stopped
before they leave the device. The AI tool gets an error response
(
403,blocked by PromptGuard Shadow), so the request fails in the tool, and the event appears in the PromptGuard app’s Activity with what was found and what to do next. A block raises no desktop notification; only a coached prompt does (below). - Coach: a prompt stopped only because one detection model flagged it. The person can send it anyway with a reason; see Coaching and overrides.
- Redact: PII is masked on the device, so the AI tool never receives the raw value and the employee still gets useful help.
- Flag: sent, and reported to your organization.
- Allow: everything else passes through untouched.
{category, count} summary of what was taken out so the engine isn’t
blinded by the masking. Raw prompt text is not something the agent sends
anywhere. Devices pointed at an engine we don’t run go further and default to
sending no prompt content at all: see
What the engine is shown.
If the engine is ever unreachable, the agent fails open by default: traffic
is allowed through rather than blocking the employee’s work. A refused connection
fails open immediately; an engine that accepts the connection but stalls gets a
30-second timeout. Organizations that need the opposite trade can set
on_engine_unreachable to hold, and a prompt the engine couldn’t be asked
about is then not sent at all. Either way it is never silent: every prompt the
agent sends without a verdict is counted and reported to your organization, on
the devices table and as an alert to your SIEM, see
If the engine cannot be reached.
See Troubleshooting for what an outage looks like
and Privacy & Data Handling for what is
logged.
Coaching and overrides
When the only reason to stop a prompt is a finding from one detection model, the agent stops it with a message that says so and gives a reference such asC-1A2B3C4D. To send it anyway, the person gives a reason, from the PromptGuard
notification, the event in Activity, the browser extension’s warning, or the
command line:
pgshadow override
with no reference lists the prompts that can still be sent anyway. The reason is
logged on the device and reported to your organization like any other decision.
Secrets, your organization’s own rules and prompts several detectors agree on are
always blocked outright, and the managed key
single_model_findings: block
turns coaching off.
Two ways to deploy
Self-serve
A user installs it, allows the network extension (Mac) and trusts the
certificate once. Good for pilots and smaller teams. The user can turn
protection off.
Managed by your MDM
Pushed by your MDM with managed configuration:
enrolled by token, settings locked, and with
user_controls: locked the
person can’t switch protection off or quit the app. On a Mac, profiles
pre-approve the network extension. Each device still asks its user to trust
its own certificate once.Honest limits
A few things are out of scope by design or still in progress. The short version:It needs a certificate to read encrypted traffic
It needs a certificate to read encrypted traffic
Inspecting HTTPS means terminating TLS, which requires a trusted certificate
on the device, in both deployment tiers. Each device creates its own
certificate authority (“PromptGuard Shadow CA”) and asks its user to trust
it once; MDM can’t pre-approve it. The agent reads content on the device and
sends it to the engine for a verdict; the engine logs the verdict with a
masked preview.
Certificate-pinned apps, QUIC and WebSockets
Certificate-pinned apps, QUIC and WebSockets
An app that pins its own certificate refuses the agent’s, so its requests
fail while its tool is monitored; switching the tool off lets it through
uninspected. Where only the system proxy applies, QUIC/HTTP-3 can route
around it, and text sent over a WebSocket is not read. Images are sent to
the engine for OCR; nothing is read from them on the device.
Updates
The agent keeps itself current, you shouldn’t have to think about versions:- Automatic by default. Updates download and install in the background. In the app’s Settings you can switch the update mode to Notify me (you approve each update) or Off.
- Every update is signed. Update packages are cryptographically signed and verified against a public key embedded in the app before anything is installed, an unsigned or tampered package is rejected.
- Staged rollout. New versions roll out to a growing percentage of devices, with a kill-switch on our side that can halt a rollout if a problem is found.
- Minimum-version floor. We can mark versions below a floor as dangerously outdated, which forces an update. Until it updates, a stale agent keeps protecting with its current policy, it never disarms, but coverage-reducing controls (like turning protection off) are locked.
- Beta channel. Opt in from Settings to receive pre-release builds early.
updater_enabledoff stops every update check. No release feed, no version-policy call. The device still polls its own engine for your organization’s update settings, which is also how it heartbeats.update_url, pointing at thelatest.jsonof your mirror of our signed releases, becomes the only update source, no dynamic endpoint on the engine host, and no GitHub fallback. Mirroring doesn’t mean re-signing: every artifact is still verified against the public key compiled into the app, wherever it came from, so a mirror cannot substitute a build of its own.
Menu bar app
The agent lives in your menu bar (macOS) or system tray (Windows / Linux):- The shield icon shows protection state at a glance: a filled shield means protected; an outline means protection is off. Hover for a tooltip with the current status.
- The menu shows protection status, Turn protection on/off, Open PromptGuard, Check for updates, Collect diagnostics… and Quit.
- Open PromptGuard opens the app window, home, Activity (every verdict, with detail per event), AI tools, settings, and help.
- Quitting the app stops the checking: AI traffic goes straight through
until it is opened again (unless your organization set
headless: true).
user_controls (no off switch, no Quit) and control_panel (a status icon
only, or nothing at all); see
Managed configuration.
Command line
The app carries a command-line tool,pgshadow. It isn’t on your PATH on
macOS or Windows: on a Mac it is
/Applications/PromptGuard Shadow.app/Contents/MacOS/pgshadow, on Windows
pgshadow.exe in the app’s install folder, and the Linux .deb and .rpm
install /usr/bin/pgshadow.
Next steps
Roll it out to your team
Enroll many devices with scoped, revocable credentials.
Choose where your data runs
Cloud, hybrid, or fully air-gapped.