Troubleshooting

Diagnose and resolve common issues with the Velatir desktop client: fleet rollout, updates, and the CLI

Overview

To diagnose most issues, run:

velatir status
velatir logs --host -f

Then reproduce the issue 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.

On Intune, upload the .mobileconfig from the enterprise builder as Devices → Configuration → Create → Templates → Custom — not a Preference file.

Set the key directly to get the device working now, then correct the profile:

sudo velatir set-api-key --key vltr_ingest_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_ingest_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.

Traces and coverage

Traces are not appearing in the dashboard

Confirm in this order:

1. Velatir is running. velatir status should show the host running; velatir health should be Ok.
2. Ingest key configured. velatir get-config should show a masked ingest key. If empty, set it: velatir set-api-key --key vltr_ingest_....
3. The activity is in a covered place. Browser AI is covered by the extension the agent deploys. Desktop apps are reported as installed or launched, not as prompt-and-response traces. See Overview.
4. 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.

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, or (rarely) a failed update. Reset to a known-good state by reapplying the ingest key:

velatir set-api-key --key vltr_ingest_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

Velatir cannot reach the backend

The agent uses outbound HTTPS. If a firewall, VPN, or zero-trust agent blocks unknown destinations, allow api.velatir.com and Velatir’s update storage.

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.

How it works

What the desktop client does on each device.