Troubleshooting
This page is organized by symptom: find the thing you are seeing, then work down the likely causes. Most issues fall into one of four buckets — the agent is not running, the certificate is not trusted, an application breaks under interception, or another network tool is in the way.
The fastest triage is to answer two questions in order:
- Is the agent running? Check the Cerbera status in the menu bar (macOS) or system tray (Windows).
- Is traffic being intercepted? Open a known AI tool (for example ChatGPT in the browser) and confirm the request appears in your Cerbera dashboard.
If (1) is yes and (2) is no, you almost certainly have a certificate or passthrough issue, not a connectivity issue.
Am I Being Intercepted?
Before anything else, isolate whether the problem is interception or general connectivity:
Test a known-good AI tool
Visit a tool Cerbera recognizes (for example ChatGPT) and send a request. If the rule match shows up in the dashboard, interception is working and the problem is specific to the app that is failing.
Test a non-AI site
Open any ordinary website. Because Cerbera is allow-by-default for traffic it does not recognize, normal browsing should be completely unaffected. If general browsing is also broken, the issue is connectivity or a conflicting network tool, not Cerbera's AI rules.
The Agent Is Not Running
Symptoms: No requests appear in the dashboard for any tool; the menu bar / tray status is off or missing.
| Likely cause | What to check | Fix |
|---|---|---|
| MDM package not yet installed | Confirm the device shows the Cerbera profile/app as installed in your MDM | Re-push the package from Jamf / Intune. See Deployment. |
| Restart skipped after install | The proxy activates after the post-install restart | Restart the device. |
| System extension / network filter not approved (macOS) | macOS prompts to approve the network extension on first launch | Approve it, or pre-approve it via an MDM configuration profile so users never see the prompt. |
| Agent crashed or was stopped | Menu bar / tray status | Restart the agent; if it recurs, see Check Agent Status & Logs below. |
Check Agent Status & Logs
The menu bar / tray icon covers the common case, but if you need to confirm the agent yourself or pull its logs for support, use the steps for your OS:
macOS
Confirm it's running:
sudo launchctl list | grep tech.bastion.aiproxy
A line starting with a PID (not -) means the agent is active.
Get the logs:
tail -f /var/log/tech.bastion.aiproxy.log
Or open Console.app and search for tech.bastion.aiproxy.
Restart it:
sudo launchctl kickstart -k system/tech.bastion.aiproxy
Windows
Confirm it's running: open Services (services.msc) and check that BastionAIProxy shows as Running, or from PowerShell:
Get-Service BastionAIProxy
Get the logs: a Windows service has no console, so the agent writes to the Event Log instead of a file. Open Event Viewer → Windows Logs → Application, and filter by source BastionAIProxy.
Restart it:
Restart-Service BastionAIProxy
Linux
Confirm it's running:
systemctl status bastion-aisecurity.service
Get the logs:
journalctl -u bastion-aisecurity.service -f
Restart it:
sudo systemctl restart bastion-aisecurity.service
Firefox keeps its own certificate store separate from the system one. If pages only fail to load in Firefox, confirm the Cerbera certificate was added to each Firefox profile on the device, then restart the browser.
Traffic Is Not Being Intercepted
Symptoms: The agent is running, ordinary browsing works, but a specific AI tool's traffic never shows up and no rule matches.
| Likely cause | What to check | Fix |
|---|---|---|
| Tool not yet in the catalog | Is the tool one Cerbera recognizes? Allow-by-default means unrecognized AI traffic is passed through silently. | If it is a new or exotic client, ask support to add it to the catalog. See AI Discovery. |
| Host is on a passthrough list | The destination may be explicitly excluded from decryption | Review your passthrough / exception entries. See Exceptions & Remediation. |
| Provider changed its client API | A provider may have shipped a new private API format overnight | This is expected and safe — the new format is allowed through until the catalog is updated. Report it so the rule can be refreshed. |
The Certificate Is Not Trusted
Symptoms: TLS / certificate warnings in the browser, or SSL certificate problem / unable to get local issuer certificate errors from a tool or CLI.
Cerbera inspects encrypted traffic by performing TLS interception with a per-device certificate that the MDM installs into the device trust store. If a client does not trust that certificate, it refuses the connection.
| Likely cause | What to check | Fix |
|---|---|---|
| Cert profile not deployed | Is the Cerbera certificate present in the system trust store? | Re-push the certificate profile from the MDM. |
| App uses its own trust store | Firefox, Java, Node.js, and many CLI tools ignore the OS trust store | Point the tool at the OS/Cerbera CA (for example a NODE_EXTRA_CA_CERTS / REQUESTS_CA_BUNDLE–style environment variable), or add the host to passthrough. |
| Certificate pinning | See the next section — this is a distinct failure mode | Add the host to passthrough. |
Installing the certificate via MDM makes the operating system trust it. Several important tools maintain their own trust stores and will still reject the certificate until they are configured separately, or the host is passed through without decryption.
An Application Breaks Under Interception (Certificate Pinning)
Symptoms: One specific app fails to connect, hangs, or reports a network error — while everything else works. There is often no TLS warning, because the app silently refuses the connection.
This is certificate pinning: the app is built to trust one specific certificate issuer rather than the device trust store, so it rejects Cerbera's per-device certificate even though the certificate is correctly trusted by the OS. Pinning cannot be "fixed" on the client; the resolution is to pass the host through without decrypting it.
Confirm it is pinning, not trust
If ordinary browsers work but one native app or CLI fails, and re-checking the certificate install does not help, treat it as pinning.
Add the host to passthrough
Add the affected destination to your passthrough / exception list so Cerbera matches it at the connection layer but never decrypts it. See Exceptions & Remediation.
When you pass a host through, Cerbera no longer monitors, redacts, or blocks its traffic — it only sees that a connection was made. This is the right trade-off for pinned apps and for sensitive destinations (banking, health) you deliberately choose not to inspect.
Conflicts With a VPN, EDR, or Secure Web Gateway
Symptoms: Intermittent connectivity, slowness, or interception breaking only when another network tool is active.
Cerbera installs as a system proxy, so it can interact with other tools that sit in the network path. See Deployment for the supported coexistence guidance.
| Conflicting tool | Typical symptom | Fix |
|---|---|---|
| Full-tunnel VPN / ZTNA (e.g. Cato) | AI traffic routes around or ahead of Cerbera | Confirm the chaining order so device-side interception happens before the tunnel. |
| EDR / antivirus | The agent's local process is blocked or quarantined | Add the Cerbera process to the EDR allowlist. |
| Another TLS-intercepting SWG (e.g. Zscaler) | Double interception or certificate errors | Avoid stacking two decryptors on the same AI traffic; scope one of them to passthrough for those hosts. |
A Request Was Blocked and Should Not Have Been
Symptoms: A user hits a Cerbera block page, or a coding agent reports that a call did not succeed.
This is usually a rule that is broader than intended rather than a malfunction. Use the exception workflow rather than disabling the proxy:
- The user can request an exception (today by email, with an in-product Request exception button on the roadmap). See Exceptions & Remediation.
- If you are early in rollout, consider running in monitor-only mode while you tune policy. See Rules.
What to Send Support
When you contact support, attaching the agent's status and logs speeds up resolution — pull them using the Check Agent Status & Logs steps for your OS above. By design this does not include prompt or response bodies unless logging is explicitly enabled. See Privacy.
When opening a ticket, include:
- The agent status and logs from the steps above.
- What you were doing and the exact tool or URL that failed.
- Whether ordinary (non-AI) browsing also failed.
- Whether a VPN, EDR, or other SWG was active.
Emergency: Unblock a User Immediately
If the proxy is blocking someone and you need them productive right now, it can be uninstalled in one click through the MDM, which removes interception immediately while the cause is investigated. See Deployment.