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 performs TLS interception on supported AI applications. By default it uses a certificate authority issued by Velatir, which is installed into the operating system trust store at install time. Organisations that already operate an internal certificate authority can supply their own CA instead. The desktop client will use it as the local MITM authority, so existing trust stores on managed devices do not need to trust a new root.

​
When to Use It

Choose your own CA if you…Use the default Velatir CA if you…
Already distribute an internal CA to managed devicesAre evaluating Velatir or running a pilot
Have policies that prohibit adding third-party roots to your trust storeDo not have an internal CA in place
Want to consolidate certificate ownership and rotation under one processWant the simplest install path
For pilots and individual evaluation, the default Velatir CA is the right choice. Bring your own CA when you are ready to align Velatir with your organisation’s existing certificate management.

​
What to Provide

You supply a PFX (PKCS#12) bundle that contains:
  • The CA certificate
  • The matching private key
  • Any intermediate certificates required to chain to the root your devices trust
The desktop client keeps the PFX bundle outside the operating system trust stores. Only the bundled certificate is presented during TLS termination; the private key is used by the local proxy and never leaves the device.
The certificate must be a CA (subject and issuer matching, keyUsage including keyCertSign, and an appropriate basicConstraints extension). A leaf certificate signed by your CA will not work because the proxy needs to issue per-host certificates on the fly.

​
Single-Device Setup

For evaluation on a single device, use the CLI. The host restarts automatically and re-binds to the new authority. 
velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password'
After running the command, verify the change took effect: 
velatir get-config
velatir status
get-config lists the active certificate fingerprint and status confirms the host is running on the new authority.

​
Organisation-Wide Setup

Distribute the PFX bundle the same way you distribute any sensitive configuration file, and point the desktop client at it. The recommended pattern is to deploy the bundle from your MDM platform first, then deploy the desktop client with the bundle path baked into the install command.

​
Windows (Intune)

  1. Deploy the PFX file to a known path on managed devices using an Intune file deployment policy (for example, C:\ProgramData\Velatir\byo-ca.pfx).
  2. In the Velatir MSI command-line arguments, point to it: 
    /qn VELATIR_API_KEY="vltr_..." VELATIR_BYO_CA_PATH="C:\ProgramData\Velatir\byo-ca.pfx" VELATIR_BYO_CA_PASSWORD="<password>"

​
macOS (Jamf Pro)

  1. Deploy the PFX file via a Jamf file payload (for example, /Library/Application Support/Velatir/byo-ca.pfx).
  2. In the API-key staging script, additionally call: 
    /usr/local/bin/velatir set-ca \
  --path "/Library/Application Support/Velatir/byo-ca.pfx" \
  --password "<password>"
See Enterprise deployment for the full Intune and Jamf Pro deployment flow that wraps these steps.

​
Rotating the Certificate Authority

Rotate by deploying the new PFX to the same path and redeploying the install command or rerunning the set-ca script. The host restarts automatically and re-binds to the new authority. For lower-risk rotations:
  1. Stage the new CA in a small device group first.
  2. Confirm velatir status reports the new fingerprint and interactions are still flowing to the dashboard.
  3. Expand the rollout group by group.
Because the desktop client restarts the host on set-ca, in-flight interactions may produce a single failed trace at the moment of rotation. Plan rotations during low-activity periods if your AI workloads are sensitive to that.

​
Removing the Custom Certificate Authority

To revert to the Velatir-issued CA, run: 
velatir set-ca --path '' --password ''
The host restarts and re-binds to the default Velatir CA bundled with the install.

​
Verification

After installing or rotating the CA, validate that supported applications still see a valid certificate chain: 
velatir logs --host -f
Trigger an interaction in a supported AI application. The host log should show a successful TLS handshake against the new authority. If applications report certificate errors after rotation, see Troubleshooting for the runtime-specific cases.

​
Next Steps

Enterprise deployment

The Intune and Jamf Pro flows that wrap bring-your-own-CA distribution.

Permissions

How the desktop client handles certificates at install time.

CLI reference

Detail on the set-ca and get-config commands.

Troubleshooting

Diagnose certificate trust issues after a rotation.