Endpoint Agent · Step 7 of 7

Troubleshooting

Start with the 30-second triage — it diagnoses roughly 80% of field issues. If triage is all-green but behavior is still wrong, capture a diagnostic bundle and escalate.

30-second triage (Windows)

Run in elevated PowerShell. A healthy endpoint shows the service Running, WinDivert filters present, both CAs in the trust stores, and the extension force-installed.

PowerShell (admin)

# 1 · Service running / automatic
Get-Service | Where-Object { $_.Name -match 'quilrai|quilr' } | Select Name, Status, StartType

# 2 · WinDivert filter / driver registered
netsh wfp show state file=$env:TEMP\wfp.xml | Out-Null
Select-String $env:TEMP\wfp.xml -Pattern 'quilr' -SimpleMatch | Select -First 5

# 3 · CA chain in Local Machine trust stores
certutil -store Root | findstr /i quilr
certutil -store CA   | findstr /i quilr

# 4 · Browser extension force-installed
Get-ChildItem 'HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist', `
  'HKLM:\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist' -EA SilentlyContinue | Get-ItemProperty

30-second triage (macOS)

Seven quick checks. A healthy endpoint shows: agent process running, system extension [activated enabled], two CAs in the keychain, and FDA allowed=1.

bash · sudo

# 1 · Agent process
pgrep -lf "quilrai|quilrai-proxy"

# 2 · Network Extension status
systemextensionsctl list | grep -i quilr

# 3 · Content filter present
profiles show -type configuration | grep -A2 -i "ContentFilter"

# 4 · CA chain in System keychain (expect 2)
security find-certificate -a /Library/Keychains/System.keychain | grep -ci quilr

# 5 · Full Disk Access (expect allowed=1)
sqlite3 "/Library/Application Support/com.apple.TCC/TCC.db" \
  "select client, allowed from access where service='kTCCServiceSystemPolicyAllFiles' and client like '%quilr%';"

# 6 · API reachability (expect 200/401/405 from each)
for u in quilr-hub.quilr.ai secure.quilr.ai dlpone.quilr.ai; do
  curl -s -o /dev/null -w "%{http_code}  $u\n" -X POST -d '{}' -H 'content-type: application/json' "https://$u"
done

# 7 · Profile count (expect 3)
profiles list | grep -i quilr | wc -l

Required network allow-list

These four must be reachable, allowed by SWG/DNS, and bypassed from SSL inspection:

Host	Purpose
`quilr-hub.quilr.ai`	CDN for installer / updates
`secure.quilr.ai` (or `QUILR_BACKEND_BASE_URL`)	BFF, config, events
`dlpone.quilr.ai` (or `QUILR_DLP_ENDPOINT`)	DLP detection
`openidconnect.googleapis.com`	Google SSO userinfo

Probe each with curl -X POST -d '{}' -H 'content-type: application/json' — expect 200, 401, or 405.

Agent log surface — what to grep for

The agent writes to three rotating log files per platform — agent.log, proxy.log, and monitor.log (paths in the platform-specific tables below). The string patterns themselves are identical across Windows and macOS. The two tables below let an operator grep the right log and immediately know whether the boot was clean or which subsystem failed.

Healthy startup — lines you should see

Tail the agent and proxy logs right after a service restart; these lines should print within ~5 seconds in roughly this order. A missing line points at the failure in the right column.

Log line (substring — greppable)	Log file	Proves
`Environment initialized`	`agent.log`	Install path, config dir, env vars all set.
`All services started successfully`	`agent.log`	Dependent services (Vault, TimeKeeper) up.
`Health monitor started`	`agent.log`	Watchdog active — will auto-restart a crashed subprocess.
`Diagnostics IPC initialized`	`agent.log`	Broker channel up; diag-events from proxy / monitor will stream.
`File logging initialized in`	`proxy.log`	Proxy’s daily-rotating appender opened the file you’re tailing.
`Proxy starting`	`proxy.log`	Proxy crossed the bootstrap gate; about to bind sockets.
`Listeners bound` (with `http_port` & `https_port` fields)	`proxy.log`	Both HTTP and HTTPS listeners successfully bound — the in-line MITM proxy is live.

Failure modes — lines you should not see, and what they mean

Filter the same logs on ERROR / error. Each row below maps an actual error string to its root cause; the Fix column points at the right Step in this troubleshooting page.

Log line	Log file	Root cause	Fix
`Packet redirector error` (`ProxyRedirectorFail`)	`proxy.log`	Windows: WinDivert driver not registered. macOS: Network Extension not approved or not installed.	Windows → verify `sc query WinDivert` returns `STATE: RUNNING`; see Step 1 of Verify Install. macOS → approve the system extension in System Settings → Privacy & Security → Allow.
`TLS handshake failed` (`ProxyTlsHandshakeFail`)	`proxy.log`	Client TLS handshake failure — usually AV/EDR running its own MITM proxy in front of Quilr, or the system root store rejecting the Quilr CA.	Verify the Quilr root cert is present in the system store (Step 4 of Verify Install). Add AV/EDR exclusion for `%ProgramFiles%\QuilrAI\` / `/Applications/QuilrAIProxy.app/`.
`Forward failed` (`ProxyForwardFail`)	`proxy.log`	Upstream host unreachable — most often `discover.quilrai.dev` or the env-specific base/DLP host blocked by firewall / DNS / SWG.	Re-run the Step 2 connectivity check; allowlist + SSL-bypass per the Required network allow-list table above.
`Certificate generation failed` (`ProxyCertFail`)	`proxy.log`	Self-signed leaf CA couldn’t be issued at runtime — disk full, permission denied on the cert dir, or AV quarantining the cert binary.	Check disk space + permissions on `%ProgramData%\QuilrAI\` / `/Library/Application Support/QuilrAI/`. Check AV/EDR quarantine for cert-gen binary.
`DLP engine initialization failed` (`ProxyDlpInitialized` error case)	`proxy.log`	DLP persona auth failed — email-discovery results missing, or the Persona service unreachable. Agent falls back to heuristic DLP only.	Re-run email-discovery (Step 3 of Verify Install). Confirm the env-specific base host is reachable on TCP/443.
`Agent must be spawned with --spawned-by-bootstrap flag`	`agent.log`	Bootstrap validation failed — somebody launched the agent binary directly instead of through the bootstrap wrapper. Security check, agent exits immediately.	Always start the agent via the service manager (Windows SCM / macOS LaunchDaemon). Never invoke `quilrai-endpoint.exe` by hand.
`Rolling file appender initialization panicked for …; using console-only logging`	stderr only (no file)	The log directory isn’t writable — permissions or disk full — so the file appender failed and proxy fell back to stderr only.	Fix permissions / free disk space on the log directory; restart the proxy service.
`No writable log directory available`	stderr only	Every candidate log dir failed the writable check — no persistent logging at all.	Same as above; verify `%PROGRAMDATA%\quilrai\logs\` / `/Library/Application Support/QuilrAI/logs/` exists and the service account owns it.

No live-tail / DevTools surface

Unlike the Browser Extension (where chrome://extensions → Inspect views: service worker gives you a live Console + Network), the Endpoint Agent has no equivalent debug socket or --tail CLI. Real-time diagnostics happen over an internal IPC broker (quilrai_broker / quilrai_alerting) consumed by the diagnostics service — not human-friendly. Disk tail is the operator’s only path:

PowerShell (admin)

# Tail today's proxy + agent logs in parallel windows
$today = Get-Date -Format yyyy-MM-dd
Get-Content "$env:PROGRAMDATA\quilrai\logs\proxy.log.$today" -Wait -Tail 100
# In a second window:
Get-Content "$env:PROGRAMDATA\quilrai\logs\agent.log.$today" -Wait -Tail 100

bash · sudo

# Tail today's proxy + agent logs (each in its own terminal pane)
TODAY=$(date +%Y-%m-%d)
sudo tail -F "/Library/Application Support/QuilrAI/logs/proxy.log.${TODAY}"
sudo tail -F "/Library/Application Support/QuilrAI/logs/agent.log.${TODAY}"

Critical log locations (macOS)

Component	Path	Purpose
Install	`/Library/Application Support/QuilrAI/logs/`	Install trace
Upload / sync	`/Library/Application Support/QuilrAI/logs/`	Cloud upload & telemetry
Agent (runtime)	`/Library/Logs/quilrai/agent.stderr.log`	Lifecycle, init, heartbeat
Proxy daemon (runtime)	`/Library/Logs/quilrai/proxy.log.YYYY-MM-DD`	DLP engine, TLS events
Templating engine (runtime)	`/Library/Logs/quilrai/templating-engine.log.YYYY-MM-DD`	UI alerts
System installer	`/var/log/install.log`	Gatekeeper, disk space

Known issues

Specific failure modes seen in the field — match the diagnostic clue in the left column to skip straight to the fix.

Diagnostic clue	Likely cause	Fix
`discover.quilrai.dev` unreachable from the endpoint (`nc -zv discover.quilrai.dev 443` reports BLOCKED, or `curl -v https://discover.quilrai.dev/` fails). Agent runs but never enrolls into a tenant.	Corporate firewall, DNS filter (Cisco Umbrella / NextDNS), or upstream SWG (Zscaler / Netskope / Symantec / Forcepoint) blocking or TLS-intercepting the host.	Allowlist `discover.quilrai.dev` on the firewall and add it to the SWG’s SSL-bypass / Do Not Decrypt list. Retest with `nc -zv … 443`. See Step 1 § Network allow-list.
Pkg install fails — `installer:` output shows “Operation not permitted” or the postinstall script returns non-zero. `sentinel-endpoint.log` mentions quarantine or codesign rejection.	AV / EDR (CrowdStrike Falcon for Mac, SentinelOne, Microsoft Defender for Endpoint on Mac, Sophos) is blocking the Network Extension binary or one of the helper tools.	Add AV / EDR exclusions for `/Applications/QuilrAIProxy.app/` and `/Library/Application Support/QuilrAI/`, then re-run the pkg. See Step 1 § AV exclusions.
Network Extension shows `[activated waiting for user]` after pkg install on an ADE-enrolled Mac, even though the SystemExtensions payload is present.	Bundle ID in the SystemExtensions payload does not match the binary, or the Team ID was changed in a re-signed build.	Re-validate the `.mobileconfig` bundle ID against `codesign -dr -` on the `.systemextension`. Request a refreshed payload from Quilr support if the binary was re-signed.
FDA prompt is shown to the user on first launch.	PPPC profile not installed, or its CodeRequirement does not match a re-signed binary.	Confirm the PPPC Custom Profile is Installed; check the TCC db for an `allowed=1, auth_reason=4` row; if the binary was re-signed, request a refreshed PPPC bundle.

Common issues & fixes

Symptom	Resolution
Package fails (exit 1)	Check Gatekeeper: `spctl --assess --type install -vvv`; ensure 300 MB free disk; remove conflicting prior builds via the uninstall script.
Codesign mismatch	The PPPC profile’s CodeRequirement must match the agent’s Team ID. Request a matching bundle if Quilr re-signs binaries.
Profile won’t install	`sudo profiles renew -type enrollment`; confirm User-Approved MDM; re-upload (don’t re-sign) in Jamf.
CA cert untrusted	Verify both root and intermediate are in the System keychain; re-upload Certificate payloads if only one is present.
FDA not granted	Confirm the PPPC profile is installed; verify a `SystemPolicyAllFiles` entry with matching CodeRequirement; query TCC for `allowed=1`.
Network Extension inactive	Confirm both SystemExtensions and WebContentFilter payloads are in the profile; bundle ID must match the binary (`codesign -dr -`); last resort `sudo systemextensionsctl reset` (Recovery Mode).

Escalation

When issues persist after triage, capture a diagnostic bundle:

bash · sudo

sudo /Applications/QuilrAIProxy.app/Contents/Resources/diag-bundle.sh \
  -o ~/Desktop/quilr-diag-$(hostname)-$(date +%Y%m%d-%H%M).tar.gz

Send the bundle to support@quilr.ai when: an all-green triage shows no console events, the Network Extension crash-loops, or genuine apps report TLS errors. Include the one-liner output, functional-test results, log files, tenant UUID, device hostname, agent version, the test time window, OS version, and whether an upstream SWG is present.

🧹

Clean uninstall Run the bundled uninstaller — sudo "/Library/Application Support/QuilrAI/quilrai-endpoint-uninstaller" — which stops the processes, removes the system extension, and deletes the LaunchDaemons, app, and config folders. Then unscope the profiles in your MDM. Do not delete the CA from the keychain unless you are also rolling back the certificate profile.

Critical log locations (Windows)

Component	Path	Purpose
Agent runtime (all services)	`%PROGRAMDATA%\quilrai\logs\`	Root directory for every sentinel-service trace (proxy, templating engine, broker)
Proxy daemon (runtime)	`%PROGRAMDATA%\quilrai\logs\proxy.log.YYYY-MM-DD`	DLP engine, TLS interception, `flow.matched` events — daily-rotating
Templating engine (runtime)	`%PROGRAMDATA%\quilrai\logs\templating-engine.log.YYYY-MM-DD`	DLP alert popups — daily-rotating, only active when an alert renders
IPC broker (runtime)	`%PROGRAMDATA%\quilrai\logs\agent.stderr.log` (also `agent.stdout.log`)	Lifecycle, init, heartbeat, inter-process broker traffic
MSI install — interactive (signed-in user)	`%TEMP%\sentinel-msi-install.log` (= `C:\Users\<USER>\AppData\Local\Temp\sentinel-msi-install.log`)	MSI verbose trace when the user double-clicked / msiexec'd the package
MSI install — SYSTEM (MDM-pushed)	`C:\Windows\Temp\sentinel-msi-install.log`	Same trace when Intune Win32 / ManageEngine / GPO ran the MSI as `LocalSystem`
MSI uninstall / rollback	`%TEMP%\sentinel-msi-uninstall.log` or `C:\Windows\Temp\sentinel-msi-uninstall.log`	Rollback / uninstall verbose trace — mirror of the install log
Intune Management Extension	`%PROGRAMDATA%\Microsoft\IntuneManagementExtension\Logs\IntuneManagementExtension.log`	Win32 app download · hash check · install orchestration (only when Intune pushed the MSI)
Windows Event Log — System	`Get-WinEvent -LogName System \| ? { $_.ProviderName -match 'WinDivert' } \| Select -First 50`	WinDivert kernel-driver load / registration failures (run elevated)
Windows Event Log — Application	`Get-WinEvent -LogName Application \| ? { $_.ProviderName -match 'Quilr' } \| Select -First 50`	User-mode service crashes · uncaught exceptions surfaced to WER

Templating-engine / broker filenames mirror the macOS layout; if a file is missing on a given build, confirm the exact name with Quilr support before escalating.

Known issues

Specific failure modes seen in the field — match the diagnostic clue in the left column to skip straight to the fix.

Diagnostic clue	Likely cause	Fix
`discover.quilrai.dev` unreachable from the endpoint (timeout / DNS fail / SSL handshake error). `Test-NetConnection discover.quilrai.dev -Port 443` returns `BLOCKED`. Agent runs but no events reach the console, log shows “discover failed” / no tenant resolution.	Corporate firewall, DNS filter (Cisco Umbrella / Defender DNS / NetSweeper / iboss), or upstream SWG (Zscaler / Netskope / Forcepoint / Symantec) is blocking or TLS-intercepting `discover.quilrai.dev`.	Allowlist `discover.quilrai.dev` on the firewall and add it to the SWG’s SSL-bypass / Do Not Decrypt list. Retest with `Test-NetConnection`. See Step 1 § Network allow-list.
MSI install fails with exit code 1603 (“Fatal error during installation”). The install log `%TEMP%\sentinel-msi-install.log` contains lines like `MSI (s) (XX:XX) Return value 3.` followed by a CustomAction or driver-registration failure.	AV / EDR (CrowdStrike Falcon, SentinelOne, Microsoft Defender for Endpoint, Sophos, Trellix, …) is quarantining the WinDivert driver or the MSI CustomAction at install time.	Add AV / EDR exclusions for `%ProgramFiles%\QuilrAI\` and `%ProgramData%\QuilrAI\`, then re-run the MSI. Confirm by tailing the AV quarantine log around the install attempt; quarantined files referencing `WinDivert` / `QuilrAI` are a positive match. See Step 1 § AV exclusions.
MSI install fails with exit code 1618 (“Another installation is already in progress”).	Concurrent MSI install — Windows Installer is single-threaded; Intune Management Extension and a manual `msiexec` can race.	Wait 60 s and re-run the install, or restart the `msiserver` service.
`sc query WinDivert` returns “The specified service does not exist as an installed service” even though the MSI says it succeeded.	WinDivert driver was loaded but failed to register (Authenticode revoked, mismatched OS build, AV blocking driver registration).	Check the AV/EDR live block log first (most common cause). If clean, capture the MSI install log and the Windows System Event log at install time; escalate with the WinDivert error code.
Agent installed and service running, but every probe to `app.quilr.ai` / `dlpone.quilr.ai` returns HTTP `200` with HTML body (a login page).	Captive portal or SWG block page replacing the response.	SSL-bypass the Quilr backplane hosts on the SWG; revisit captive-portal coverage if the endpoint is roaming. See Step 1 § Network allow-list.

Common issues & fixes

Symptom	Resolution
Service won’t start / TLS errors	Missing intermediate CA — confirm both certs imported (`certutil -store Root` and `-store CA`); the intermediate is required for the chain.
No Quilr cert in store	CA script not applied or wrong store — re-run `certutil -addstore -f Root` / `-addstore -f CA`, or let the MSI re-import; redeploy.
Agent installed but idle	`TENANTID` was omitted from the MSI command — reinstall with `TENANTID=<TENANT-ID>`.
MDM config stuck / not applied	Trigger a manual sync (Intune) or refresh cycle (Endpoint Central); for GPO run `gpupdate /force`.
Browser extension missing	Verify the `ExtensionInstallForcelist` value and extension ID/URL; restart the browser; redeploy the policy.

Escalation

Collect the service status, certutil outputs, the tail of %PROGRAMDATA%\quilrai\logs\proxy.log.*, and the MSI logs from %WINDIR%\Temp\. Send them to support@quilr.ai with the tenant UUID, device hostname, agent version, OS version, and whether an upstream SWG is present.

🧹

Clean uninstall Change the MSI assignment to Uninstall (or run msiexec /x "{QUILR-MSI-PRODUCT-CODE}" /qn), unassign the CA certificate profiles, and remove the extension force-install policy. Leave the CAs unless you are also rolling back the certificate profiles.

🎉

Endpoint Agent track complete You’ve covered prerequisites, validation, manual + MDM installation, and troubleshooting. To protect Chrome and Edge, move on to the Browser Extension track.

←BackVerify MDM Install Step 7 of 7 Next trackBrowser Extension→