Skip to main content
The desktop agent is the part your team installs. Once it’s on, it watches the AI tools they already use and enforces your policy on the device, before a prompt or file reaches the AI tool. One agent covers both the AI apps in the browser (ChatGPT, Claude) and the AI APIs behind coding tools (IDE assistants, SDKs); the browser extension adds a check on the page itself, which closes the browser’s WebSocket and QUIC gaps. It ships today on macOS (signed and notarized), Windows (the installer is code-signed by PG TECH LTD from the first release after our certificate is issued, and unsigned before that; each release’s notes say which, and if SmartScreen warns on first run the two-click path is in the quickstart), and Linux. All three are downloadable from promptguard.co/download.

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.
The rest of this page is the reference, what’s covered, how it enforces, the deployment tiers, and the honest limits.

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.
macOS gap in agent 0.10.x. When the network extension carries traffic (the default on macOS 13 and later), it routes only its own, shorter list of AI hosts, and the system proxy is removed. Traffic to Cursor, GitHub Copilot, Microsoft Copilot, Hugging Face, Meta AI, Poe and DeepSeek’s web chat (chat.deepseek.com), and ChatGPT file uploads (oaiusercontent.com), is then not inspected on the network path. In the browser, the browser extension still checks prompts typed on those sites. This is a known agent bug (promptguard-shadow-desktop#317), and the list here will shrink when it is fixed. Windows and Linux are not affected.
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.
A Hold is recorded when your organization holds prompts while the engine can’t be reached (below). To reach that verdict the agent masks on the device first, then asks. The prompt it sends, with text extracted from attachments, and any images or audio, already has every masker finding replaced by its placeholder, and it travels with a {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 as C-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:
and then sends the same prompt again within five minutes. 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.
What managed deployment does not have yet: a certificate your MDM deploys (every device creates its own, so the one trust prompt remains), and the Windows filtering driver that captures every app, which is a preview: it is test-signed and doesn’t load on production Windows, so Windows devices use the system proxy and the Claude Code and Codex routes. A local administrator can always uninstall.

Honest limits

A few things are out of scope by design or still in progress. The short version:
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.
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.
For the full, honest list, and how to mitigate each one, see Known Limitations.

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.
Update checks go to the engine the agent is signed in to, and fall back to PromptGuard’s GitHub releases if that engine doesn’t answer. Two managed-configuration keys take that traffic off PromptGuard entirely, and both are locked against local change:
  • updater_enabled off 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 the latest.json of 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.
A freshly imaged machine with neither a device credential nor any managed configuration makes none of those calls, not the release feed, not the version policy. With a managed enrollment token it makes exactly one, the enrollment, and starts the rest on the cycle after it has a credential. See Managed configuration for where to write those keys. On managed fleets, org admins can also force the update mode, pin the release channel, and set a minimum version for every device, see Fleet Enrollment. 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).
Your organization can lock or hide parts of this with the managed keys 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.
Last modified on November 16, 2026