Skip to main content

​
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.

​
Interception

Confirm in this order:
  1. Velatir is running. velatir status should show capture active.
  2. Ingest key configured. velatir get-config should show a masked ingest key. If empty, set it: velatir set-api-key --key vltr_....
  3. The application is supported. Velatir captures only supported applications. See Overview.
  4. Certificate trust. Some runtimes use their own trust store. See Certificate not trusted by a specific runtime.
  5. 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.
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”).
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

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://...
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

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 it keeps disappearing, run velatir logs -f (it reconnects once the client comes up) and share the output with support.
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
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 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.
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

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.
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.