Installation

Patronus Desktop protects supported AI traffic on macOS and Windows. First launch guides you through the required operating-system approvals.

Requirements

• macOS or Windows with permission to install local system components.
• The Patronus installer for your operating system.
• Network access during first setup.
• Admin approval when the operating system asks for it.

Install on macOS

1. Download the macOS DMG from the Patronus download page.
2. Open the DMG and move Patronus Desktop.app into /Applications.
3. Start Patronus Desktop.app.
4. Follow the setup screen in Patronus.
5. Approve the macOS prompts shown during setup.
6. Start protection from Patronus Desktop.

If macOS asks for Network Extension approval, approve Patronus in System Settings and return to Patronus Desktop.

Install on Windows

1. Download the Windows installer from the Patronus download page.
2. Run the installer and approve the Windows elevation prompt.
3. Complete the installer. If Windows needs an additional Microsoft WebView component, the installer will guide you through it.
4. Start Patronus Desktop from the Start Menu.
5. Follow the setup screen in Patronus.
6. Start protection from Patronus Desktop.

If Windows requires additional security approval, complete the prompt and return to Patronus Desktop.

Onboarding

On first launch, onboarding checks local protection components, repairs missing pieces, and requests required operating-system approvals.

macOS onboarding

On macOS, onboarding covers:

1. Installing or updating the privileged helper.
2. Generating the local mitmproxy certificate authority if it does not exist yet.
3. Trusting the mitmproxy CA in the system trust store.
4. Configuring runtime CA environment values for supported CLI and SDK runtimes.
5. Asking macOS to approve the Patronus Network Extension and proxy configuration.
6. Starting protection after the approvals are complete.

If any step is missing later, Patronus shows a repair state and reruns the relevant onboarding action.

Windows onboarding

On Windows, onboarding covers:

1. Installing or updating the Patronus helper service.
2. Generating the local mitmproxy certificate authority if it does not exist yet.
3. Trusting the mitmproxy CA in the Windows trusted root store.
4. Configuring runtime CA environment values for supported CLI and SDK runtimes.
5. Preparing the Windows traffic capture path used by Patronus.
6. Starting protection after the required approvals are complete.

If Windows asks for elevation or security approval, complete the prompt and return to Patronus Desktop.

Approve The Network Extension (macOS)

Patronus uses a Network Extension to observe AI traffic on macOS. On first start, macOS asks you to allow it:

1. Open System Settings → Network → Filters

When Patronus prompts you, open System Settings. Patronus appears in Network → Filters as a pending content filter.

2. Allow proxy changes

macOS asks you to allow Patronus to add a proxy configuration. Approve the prompt with Touch ID or your password.

3. Confirm the extension

Confirm that the Patronus filter is listed and enabled. Return to Patronus Desktop and continue.

If macOS does not show a prompt, open System Settings → Network → Filters manually and enable Patronus there.

Trust the local certificate authority

Patronus uses a local certificate authority (CA) to inspect supported HTTPS traffic. The client must trust that CA before Patronus can analyze the encrypted content.

• During setup, Patronus installs the CA into the system trust store through its privileged helper.
• On macOS you can verify it by opening Keychain Access → System and looking for a mitmproxy certificate marked as trusted.
• On Windows the CA lives under Certificate Manager → Trusted Root Certification Authorities.
• The active capture and inspection settings determine which connections Patronus inspects. Certificate trust alone does not determine that scope.

If the CA is missing or marked as untrusted, re-run the setup step from Patronus Desktop. Patronus will reinstall the CA through the privileged helper rather than asking you to handle certificates manually.

Restart shells and terminal sessions

After protection starts for the first time, open new terminal sessions before running CLI tools that access AI services. Tools that read proxy or certificate settings only at startup otherwise retain the previous configuration.

This typically affects:

• node and JavaScript runtimes (npm, yarn, pnpm scripts that hit AI APIs).
• python, pip, and uv-based clients (OpenAI SDK, Anthropic SDK, LangChain).
• git when configured to talk to AI-assisted code review services.
• docker and docker compose when builds or containers reach out to AI hosts.
• Long-running editors and IDE terminals. Restart the client process as well if a new terminal still inherits the old settings.

If a CLI keeps connecting without going through Patronus, restart the terminal and client, then check runtime CA support.

What Gets Installed

A standard installation includes these local components. See Privacy and retention for their data paths:

• The Patronus Desktop application in the installation location for your operating system.
• A privileged helper used to configure the system proxy, install the local CA, and start the macOS Network Extension.
• A local certificate authority added to the system trust store so encrypted AI traffic can be inspected.
• Local configuration and storage in the per-user data directory for preferences, policies, and runtime evidence.
• Local security models used by the on-device analysis available to your installation. Setup and repair prepare the required runtime components.

The desktop installation does not require a browser addon.

Verify protection

After setup:

1. Open Patronus from the tray.
2. Confirm Patronus shows protection as running.
3. Send a simple request through a supported AI app, CLI, SDK, or local model endpoint.
4. Open Traces and check that the request appears. Review its audits and policy decisions to confirm what was analyzed and how it was handled.

Update and repair

Patronus may show one of these visible update or recovery states:

• Update available means a new Patronus version can be installed.
• Repair required means Patronus needs to restore a local component before protection can start.
• Restart required means the operating system or Patronus needs a restart before protection continues.

Follow the action shown in Patronus Desktop. If protection still does not start, restart Patronus and retry.

Uninstall

Use the standard uninstall flow for your operating system:

• On macOS, use the Patronus uninstaller if one is included with your installation package.
• On Windows, uninstall Patronus from Windows Settings or the Start Menu entry provided by the installer.

The uninstaller removes the local proxy state, trusted mitmproxy CA entries, runtime CA environment values, helper services, and Patronus runtime files. If uninstall is interrupted or a local test leaves proxy or CA state behind, use the commands in Uninstall And Manual Cleanup.

After uninstalling, restart the device if the operating system asks for it.