Troubleshooting

Overview

To diagnose most issues, run:

velatir status
velatir logs --host -f

Then reproduce the issue in a supported AI application and watch the log. If the client never arrived on the device in the first place, start with Fleet and MDM instead.

Fleet and MDM

Intune reports the app state is unknown (0x87D13B67)

The app was added with the wrong app type. 0x87D13B67 is not an install failure — it means Intune has no install status for the app at all, which is also why nothing about Velatir appears in the device logs.Velatir installs a background agent under /Library, uses install scripts, and places a small stub bundle (not the self-updating host) at /Applications/Velatir.app. Intune’s Line-of-business app type cannot handle that shape: with Install as managed set to Yes it supports only a package containing a single application that installs into /Applications, and either way it detects an install solely by finding an application bundle. A quick way to tell which type you used: if the app’s properties show an Install as managed field, it is a line-of-business app.Delete the app in Intune and add it again as macOS app (PKG), following Enterprise deployment. Check the Included apps list as you go — an entry of com.velatir.agent.bootstrap is the package identifier rather than an application, and while it is listed the install can never be detected.

Intune reinstalls Velatir on every check-in

The detection rule never matches, so Intune keeps concluding the app is missing and installs it again. Confirm it on one device by looking at the install history, which should show one install rather than several in a week:

grep -i velatir /var/log/install.log | tail -20    # macOS install history
tail -20 /Library/Logs/Velatir/bootstrap.log       # Velatir's own install-time log

Fix the rule as described in Enterprise deployment: Included apps must hold com.velatir.desktopapp and not com.velatir.agent.bootstrap, with Ignore app version set to Yes.Worth correcting promptly rather than treating as noise. Each reinstall restarts the agent, so devices drop out of the dashboard for a few minutes at a time, and while the agent is down the browser extension on macOS asks users for an ingest key: Microsoft Edge does not deliver managed configuration to extensions on macOS, so the agent is what hands the extension its key.

velatir status reports it cannot reach VelatirAgent

The agent daemon is not running. Ask launchd what it holds for it:

sudo launchctl print system/com.velatir.agent | head -20

Then start it:

sudo launchctl bootout system/com.velatir.agent 2>/dev/null
sleep 3
sudo launchctl bootstrap system /Library/LaunchDaemons/com.velatir.agent.plist
sudo launchctl kickstart -k system/com.velatir.agent
velatir status

If bootstrap reports Input/output error, the label is either still being torn down, in which case waiting a few seconds and repeating clears it, or it is blocked from loading. macOS 13 and later can disable background services and an MDM can control that list, so check both:

sudo launchctl print-disabled system | grep -i velatir
sfltool dumpbtm | grep -i -A6 velatir

A disabled item has to be re-enabled wherever it was disabled: System Settings → General → Login Items & Extensions for a user choice, or a Managed Login Items payload from your MDM on a managed fleet.

The MDM reports a problem, but the device logs show nothing about Velatir

The installer never ran, so there is nothing on the device to find. Check in this order:

pkgutil --pkgs | grep -i velatir        # expect com.velatir.agent.bootstrap
grep -i velatir /var/log/install.log    # did the installer run at all?
ls -l /Library/Logs/Microsoft/Intune/   # Intune: is the management agent there?

No package receipt and nothing in install.log puts the problem in the MDM rather than on the device. With Intune, the Microsoft Intune management agent for macOS is what runs the installer, and configuration profiles arrive over a different channel — so profiles applying successfully tells you nothing about whether apps can install.To rule out the package itself, install it by hand on one device:

sudo installer -pkg Velatir-Bootstrap-macos-arm64.pkg -target /
velatir status

The ingest key profile applied, but the client has no key

Check what actually reached the device:

sudo defaults read "/Library/Managed Preferences/com.velatir.agent" ApiKey

If that prints nothing, the profile is not delivering the key. The preference domain must be com.velatir.agent and the key must be named exactly ApiKey. INGEST_KEY is the Windows MSI property and has no meaning in a configuration profile, so a profile using that name applies without error and does nothing.Set the key directly to get the device working now, then correct the profile:

sudo velatir set-api-key --key vltr_your_api_key_here

Velatir installed, but never started

Installing without an ingest key completes successfully, but the agent cannot finish setting itself up — so /Applications/Velatir.app is left pointing at nothing and will not open.Supply the key. The agent finishes setup on its next check, within a few minutes:

sudo velatir set-api-key --key vltr_your_api_key_here
velatir status

Across a fleet this usually means the app reached the devices but the profile carrying the ingest key did not. Confirm the profile is scoped to the same devices as the app.

Interception

Traces are not appearing in the dashboard

Confirm in this order:

Velatir is running. velatir status should show capture active.
Ingest key configured. velatir get-config should show a masked ingest key. If empty, set it: velatir set-api-key --key vltr_....
The application is supported. Velatir captures only supported applications. See Overview.
Certificate trust. Some runtimes use their own trust store. See Certificate not trusted by a specific runtime.
Network reachability. The device must reach api.velatir.com: curl -I https://api.velatir.com.

If all check out, run velatir logs --host -f while reproducing and share the output with support.

Some applications are captured, others are not

This is expected. Velatir only captures supported AI applications; everything else is passed through untouched.To request coverage for an application, contact your account team with the application name, vendor, operating system, and the AI provider it talks to (for example, “Editor X on Windows talks to api.anthropic.com”).

Capture will not start

Windows: usually the install did not complete correctly. Reinstall the MSI with administrator elevation. If it persists, run velatir logs -f while attempting velatir start and capture the error.macOS: usually the system extension has not been approved. Open System Settings → General → Login Items & Extensions → Network Extensions and confirm Velatir is enabled. See Permissions.

Certificates

Certificate not trusted by a specific runtime

Browsers and most native apps use the operating system trust store and pick up the Velatir CA automatically. A few runtimes use their own trust store and need explicit configuration.Node.js

export NODE_EXTRA_CA_CERTS=/path/to/velatir-ca.crt

On macOS the installer sets this automatically. Restart any Node.js process that was running before the install.Python (requests, urllib)

export SSL_CERT_FILE=/path/to/velatir-ca.crt
export REQUESTS_CA_BUNDLE=/path/to/velatir-ca.crt

JVMImport the Velatir CA into the JVM truststore:

keytool -importcert -trustcacerts \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit \
  -alias velatir \
  -file /path/to/velatir-ca.crt

curlcurl follows the OS trust store on macOS and Windows. On Linux, point it explicitly:

curl --cacert /path/to/velatir-ca.crt https://...

Certificate pinned by the application

Some applications only trust one specific certificate and reject any other. There is no workaround; Velatir detects these connections and passes them through unmodified.If a pinned application is critical to your compliance workflow, contact your account team about coverage options.

Agent and Host

`velatir status` reports the agent is unreachable

This means the Velatir process is not running.Windows: it runs as the VelatirAgent service. Start it with sc start VelatirAgent from an elevated prompt, or restart the device. If the service is missing, reinstall the MSI.macOS: relaunch Velatir from Applications, or run open /Applications/Velatir.app. If that reports the application cannot be found, it was installed without an ingest key and never finished setting itself up — see Velatir installed, but never started.If it keeps disappearing, run velatir logs -f (it reconnects once the client comes up) and share the output with support.

Velatir keeps restarting

Velatir restarts itself within 30 seconds if it stops unexpectedly. Frequent restarts usually mean a problem. Inspect the log:

velatir logs --host

Common causes: an invalid ingest key, a bad bring-your-own CA password, or (rarely) a failed update. Reset to a known-good state by reapplying the ingest key:

velatir set-api-key --key vltr_your_api_key_here

A second launch does nothing

Velatir only runs one copy at a time, so an accidental second launch exits silently. This is expected. To restart it:

velatir host restart

Updates

`velatir update` reports no new version, but I expected one

Velatir checks for updates periodically. To force a check now:

velatir update
velatir update --apply

If the version is still older than expected, or you use a tenant-specific update channel, contact support.

An update applied but the version did not change

A failed update stays on the previous version. Inspect the log:

velatir logs -f

A common cause is insufficient disk space. Free up space and retry with velatir update --apply.

Networking

VPN connected after Velatir started, and now things are odd

Velatir re-binds on its own when the network changes, so this usually resolves within seconds. If it does not:

velatir restart

See VPN compatibility.

QUIC / HTTP/3 connectivity unusual

On Windows, Velatir keeps known AI hosts on a connection it can observe; other traffic (including HTTP/3 to non-AI sites) is untouched, so this rarely causes visible issues. On macOS, QUIC is not captured at all.

Getting Help

When you contact support, attach:

velatir status --json > status.json
velatir version > version.txt
velatir logs > agent.log
velatir logs --host > host.log

These four files describe the state of the desktop client and let support reproduce most issues without further round trips.

Next Steps

FAQ

Quick answers to common questions.

CLI reference

Full command surface for diagnosing and recovering.

Permissions

What the app needs from the operating system, and why.

VPN compatibility

Detail on coexistence with corporate VPNs.

Getting Started

Platform

Velatir for Desktop

Browser extension

Connectors

Agents

Sessions & Traces

Insights

For Providers

Security & Privacy

Overview

Fleet and MDM

Interception

Certificates

Agent and Host

Updates

Networking

Getting Help

Next Steps

FAQ

CLI reference

Permissions

VPN compatibility

​Overview

​Fleet and MDM

​Interception

​Certificates

​Agent and Host

​Updates

​Networking

​Getting Help

​Next Steps

FAQ

CLI reference

Permissions

VPN compatibility

Overview

Fleet and MDM

Interception

Certificates

Agent and Host

Updates

Networking

Getting Help

Next Steps