Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velatir.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

If something is not working as expected, the fastest path to a diagnosis is usually: 
velatir status
velatir logs --host -f
Then reproduce the issue in a supported AI application and watch the log. The sections below cover the most common failure modes and what to do about each.

​
Interception

Confirm in this order:
  1. Agent and host running. Run velatir status. Both should be running and the transparent proxy should be active.
  2. API key configured. velatir get-config should show a masked API key. If it is empty, set it with velatir set-api-key --key vltr_....
  3. The application is supported. The desktop client captures traffic only from applications in the supported list. See Overview for the current coverage.
  4. Certificate trust. Some runtimes maintain their own trust stores. See Certificate not trusted by a specific runtime.
  5. Network reachability. The host needs to reach api.velatir.com. From the device, confirm with curl -I https://api.velatir.com.
If all of the above check out, run velatir logs --host -f while reproducing and share the output with support.
This is usually expected behaviour. The desktop client operates in apps-only mode: only applications mapped in the registry are decrypted. Unmapped applications are blind-relayed without interception.If you believe an application should be supported but is not, request coverage through your account team. Include the application name, vendor, the operating system, and the AI provider it talks to (for example, “Editor X on Windows talks to api.anthropic.com”).
On Windows, the most common cause is that the Wintun driver did not install correctly during MSI installation. Reinstall the MSI and confirm administrator elevation. If the issue persists, run velatir logs -f while attempting velatir start and capture the error.On macOS, the most common cause is that the system extension has not been approved. Open System Settings > General > Login Items & Extensions > Network Extensions and confirm that Velatir is enabled. See Permissions for details.

​
Certificates

Browsers and most native applications use the operating system trust store and pick up the Velatir CA automatically. A few runtimes maintain their own trust stores and need explicit configuration.Node.js
export NODE_EXTRA_CA_CERTS=/path/to/velatir-ca.crt
On macOS, the installer sets a suitable value in the user shell environment automatically. If a Node.js process was started before the install, restart it.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 using keytool:
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 by default. On Linux, point it explicitly:
curl --cacert /path/to/velatir-ca.crt https://...
Some applications pin a specific certificate or CA at compile time, refusing to trust any other authority. There is no general-purpose workaround for pinned applications. The desktop client detects pinned connections and lets them pass through unmodified.If a pinned application is critical to your compliance workflow, talk to your account team about coverage options.
The Windows installer prefers LocalMachine\Root but falls back to CurrentUser\Root for the installing account if group policy blocks machine-wide installation. If users other than the installer see certificate warnings, reinstall the MSI with elevation removed, or coordinate with your endpoint team to allow LocalMachine\Root writes for the Velatir CA.

​
Agent and Host

The CLI talks to the agent over a named pipe on Windows and a Unix socket on macOS. “Agent unreachable” means the agent process is not running.Windows. The agent should restart at next logon. To start it now, sign out and back in, or run the Velatir scheduled task manually from Task Scheduler. If the scheduled task is missing, reinstall the MSI.macOS. The agent is part of the application bundle. Relaunch Velatir from Applications, or open Terminal and run open /Applications/Velatir.app.If the agent keeps disappearing, run velatir logs -f (it will reconnect once the agent comes up) and share the output with support.
The watchdog respawns the host every 30 seconds if it has died. Frequent restarts usually indicate a crash. Inspect the host log:
velatir logs --host
Common causes:
  • An invalid API key (the host fails to authenticate and exits)
  • A corrupted payload (rare; velatir update --apply re-stages the current version)
  • A bring-your-own CA bundle with an invalid password
Reset to a known-good state by reapplying the API key:
velatir set-api-key --key vltr_your_api_key_here
The host enforces a single-instance lock so a second Velatir.exe launched by accident exits silently. This is expected. To restart the running host, use:
velatir host restart

​
Updates

The agent polls every four hours. To force a check now:
velatir update
velatir update --apply
If the version reported by the API is older than expected, or you have a tenant-specific update channel configured, contact support.
A failed update does not change current; it stays on the previous version. Inspect the agent log for the staging failure:
velatir logs -f
A common cause is insufficient disk space in the install directory. Free up space and retry with velatir update --apply.

​
Networking

The desktop client captures the network configuration at host start time. After a VPN state change, restart with:
velatir restart
See VPN compatibility for the full explanation.
The desktop client blocks outbound UDP 443 to keep AI traffic on TCP, where it is observable. This affects only HTTP/3 to public hosts and rarely causes user-visible issues. If a specific workflow depends on HTTP/3 to a non-AI destination, contact support so we can scope an exemption.

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