Skip to main content

​
Overview

The Velatir host re-evaluates a small set of checks on the interception stack every ~30 seconds and exposes the result through velatir health. Velatir is fail-safe: when a check fails it never black-holes your traffic. Depending on what broke, it either stops inspecting (and blind-relays traffic untouched) or tears down its capture route so traffic flows directly. It returns to full interception automatically once the problem clears.

​
Overall State

StateMeaningWhat Velatir does
OkAll checks pass.Full per-host inspection.
DegradedInspectionAn inspection prerequisite failed (for example, the CA is not trusted, or the end-to-end probe failed).Inspection is gated off — traffic is blind-relayed so apps keep working, but AI activity may not be traced until the issue clears.
DegradedRoutingThe capture route itself is broken or would black-hole traffic.The route is torn down so traffic flows directly (uninspected), preserving connectivity.
Each failing check carries a lever that determines the response: GateOff (leads to DegradedInspection), RouteTeardown (leads to DegradedRouting, and takes precedence), or None (informational only). A single failed probe trips degradation immediately; recovery requires two consecutive healthy probes, which prevents flapping.

​
The Checks

CheckPlatformVerifiesFails whenOn failure
api-healthz-e2eWindows, macOSA request to the API health endpoint, deliberately routed through the proxy (client → route → relay → MITM → upstream → API). Proves every moving part works together.Non-2xx response, timeout (~10s), or network error.Gate inspection off
cert-trustedWindows, macOSThe Velatir CA is installed and trusted. Without it, intercepted apps would see TLS errors.The CA is not installed or trusted.Gate inspection off
windows-routingWindowsThe routing substrate is intact: agent reachable, proxy engaged, tun2socks alive, Wintun adapter up, SOCKS relay listening, and a physical NIC resolved.Any component is down while routing is engaged.Tear route down
windows-connectivityWindowsReal traffic actually flows through the captured path, using cache-immune DNS probes. Catches full-tunnel VPNs that silently black-hole captured traffic even when every component looks alive.All probes fail while routing is engaged (then latches until a network change).Tear route down
macos-ne-providermacOSThe NETransparentProxyProvider bridge is connected while active — not “engaged but dead”.The bridge is active but the provider is disconnected.Tear route down
macos-system-extensionmacOSThe Velatir network extension is approved and enabled.The extension is not approved or enabled.Informational only — no automatic action

​
Notes on specific checks

  • windows-connectivity latches. Once it trips — typically a full-tunnel VPN black-holing the captured path — it stays failed until a network change (VPN connect/disconnect, Wi-Fi roam, or NIC change) is detected, then re-tests. This prevents a flap loop on VPNs that persistently break capture.
  • macos-system-extension is a diagnostic, not a gate. If the extension isn’t approved there is nothing to tear down — traffic simply isn’t intercepted — so this check only reports. Approve the extension in System Settings → General → Login Items & Extensions → Network Extensions.

​
Reading velatir health

velatir health

Health:    DegradedRouting
Evaluated: 2026-06-05 14:31:02 (8s ago)

Checks:
  [ ok ] api-healthz-e2e
  [ ok ] cert-trusted
  [FAIL] windows-routing
         reason: tun2socks not running; SOCKS relay not listening
         lever:  RouteTeardown
  [ ok ] windows-connectivity
  • The snapshot is marked (stale — Velatir may not be running) if it is older than two minutes.
  • velatir health --json emits the raw snapshot for monitoring tools.
  • The exit code is 0 when the state is Ok and non-zero when degraded, so velatir health works as a probe.
The snapshot is written to the host’s local app-data directory (%LOCALAPPDATA%\Velatir\DesktopApp\health.json on Windows) on every evaluation; its timestamp doubles as a liveness signal.

​
Next Steps

Troubleshooting

Resolve a degraded state.

CLI reference

The health and test commands in detail.