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

The Velatir desktop client is built from three cooperating components and a transparent proxy. Each component has a single responsibility, which keeps the surface predictable and the failure modes recoverable.
ComponentResponsibility
HostRuns the MITM proxy, parses AI traffic, and submits traces.
AgentBackground supervisor. Keeps the host alive and pulls updates.
WatchdogThe supervisor loop inside the agent. Restarts the host and cleans up networking state if anything goes wrong.
Transparent proxyOperating-system-level traffic capture. Different mechanism per platform.

​
Traffic Interception

The desktop client intercepts outbound HTTPS traffic on the user’s machine, decrypts only the traffic that belongs to supported AI applications, and lets everything else pass through untouched.

​
macOS

On macOS, traffic interception uses Apple’s NETransparentProxyProvider system extension.
  1. The system extension intercepts TCP flows at the network layer.
  2. Flows are relayed to the host process over a local Unix socket.
  3. The host runs an embedded MITM proxy that performs TLS interception on AI hosts only.
  4. The host re-establishes the upstream TLS connection and forwards traffic transparently.
The system extension is signed with Velatir’s Apple Developer ID and must be approved once by the user at first run. See Permissions for details.

​
Windows

On Windows, traffic interception uses a virtual network adapter.
  1. A Wintun TUN adapter captures outbound TCP traffic on port 443.
  2. A bundled tun2socks helper forwards packets to the local MITM proxy.
  3. A firewall rule blocks outbound UDP on port 443. This forces clients to use HTTPS over TCP rather than QUIC, so traffic remains observable.
  4. The host process performs TLS interception on AI hosts only.
The Wintun driver and tun2socks helper are installed by the MSI. See Permissions for the elevation requirements.

​
Apps-Only Mode

Decrypting every TLS connection on a managed device would be intrusive and risky. The desktop client therefore operates in apps-only mode: it only decrypts traffic that matches a known AI application. For each connection, the proxy:
  1. Reads the SNI hostname from the TLS ClientHello.
  2. Resolves the source process and matches it against the application registry.
  3. If the process, hostname, and request path all match a known descriptor, the connection is decrypted and parsed.
  4. If anything is unmatched, the connection is blind-relayed without decryption.
Unsupported traffic never gets a Velatir certificate served, which means non-AI applications behave exactly as they would without Velatir installed.

​
The Velatir Agent

The agent is a long-running background process that owns two responsibilities: keeping the host alive and applying updates. On Windows, the agent runs as VelatirAgent.exe, installed by the MSI and registered to start at user logon. On macOS, it runs as part of the installed application bundle. The agent itself never touches network state. Its only job is to make sure the host is running and current.

​
Bootstrap and Payload Layout

The MSI on Windows and the installer package on macOS are intentionally small. They install the agent and a public certificate, then hand off.
  1. The installer launches the agent in --bootstrap mode.
  2. The agent downloads the current desktop-app payload (the host, parsers, and platform binaries) from Velatir’s distribution storage.
  3. The payload is staged into a versioned folder, and a current symlink points at it.
  4. New versions are staged side-by-side and swapped atomically. The previous version stays on disk until the next update completes successfully.

​
The Watchdog

The watchdog is the supervisor loop inside the agent. It runs every 30 seconds and exists to keep the system in a known-good state.
CheckAction
Host process is not running, but the host binary exists.Relaunch the host immediately.
The transparent proxy is active, but the host process has gone away.Tear down the proxy networking so the device does not lose internet access.
A new payload has been staged.Drain the running host and relaunch it on the new version.
The watchdog is what makes the desktop client self-healing. If the host crashes, the user does not need to do anything: within 30 seconds the agent has noticed and restarted it. If the host disappears while the transparent proxy is bound to the network, the agent tears the proxy down rather than leaving the device in a state where traffic is sinkholed.

​
Auto-Update

The agent polls for new versions every four hours. When a new payload is available it stages the new version, drains the running host, swaps the current symlink, and relaunches. Users can force an update from the CLI: 
velatir update --apply
This makes the update process synchronous and is useful when validating a fix or rolling out a critical change. See CLI reference for the full command surface. If an update fails to verify or stage, the watchdog leaves the previous version running. There is no partially-installed state.

​
Certificate Handling

Because the desktop client performs TLS interception on AI traffic, applications must trust the certificate that the local proxy presents.
  • Windows. The Velatir CA certificate is added to LocalMachine\Root by the installer. If group policy blocks machine-wide installation, it falls back to CurrentUser\Root for the installing user.
  • macOS. The Velatir CA is added to the System keychain by the installer.
  • Node.js, Python, and other runtimes that maintain their own trust stores may need additional configuration. See Troubleshooting for the common cases.
For organisations that prefer to provide their own certificate authority, the desktop client supports bring your own certificate.

​
Next Steps

Permissions

What the operating system asks for and why.

VPN compatibility

How the desktop client behaves alongside corporate VPNs.

CLI reference

Control the agent, host, and updates from the command line.

Troubleshooting

Diagnose interception, certificate, and update issues.