# Assessments
Source: https://docs.velatir.com/agents/assessments
The record of every verdict your agents have reached.
## What Are Assessments?
An assessment is what an agent recorded for a single trace: the verdict it reached and why. Every time an agent reviews a trace, it leaves an assessment. The **Assessments** view under **Agents** is the full, searchable record of those verdicts across your organisation.
It is where you go to understand what your agents are catching, confirm they are behaving as you expect, and decide what to adjust.
## What Each Assessment Shows
Which interaction was reviewed, its direction, the service involved, and when it happened.
Allowed, Flagged, or Blocked, along with the agent's reasoning.
If an instruction shaped the verdict, it is shown so you can see exactly why the agent acted.
If the trace was escalated, the escalation and its status appear here too.
## Find What You Need
Search by keyword, or filter and save views so you can return to the same slice quickly.
| Filter by | Examples |
| ------------- | ---------------------------- |
| **Agent** | Gatekeeper or Data Protector |
| **Status** | Allowed, Flagged, Blocked |
| **Direction** | Inlet, Response, Signal |
| **Service** | The AI service involved |
## Turn a Verdict Into a Rule
When you review an assessment and decide how that scenario should be treated in future, you can save it as an [instruction](/agents/instructions) without leaving the page. The instruction keeps a link back to the assessment it came from, so the origin of every rule stays clear.
Reviewing assessments in the first weeks is the fastest way to tune your setup. What you see here tells you which services to allow or block and which data categories matter most.
***
Save a verdict as a forward-looking rule.
See assessments in the context of the full interaction.
# Configuring Agents
Source: https://docs.velatir.com/agents/configuring-agents
Set agents at the organisation level, override per workspace, and roll out with confidence.
## Two Levels of Configuration
Agent configuration follows a simple model. You set organisation-level defaults that apply everywhere, then optionally override them for specific workspaces. This gives you central control with the flexibility to treat some teams differently.
## Organisation Defaults
Your organisation settings define the baseline for each agent: its role, and what it acts on. For Gatekeeper that is your default rule and exceptions. For Data Protector that is the categories you enable and any instructions you assign. These defaults apply to every workspace unless a workspace overrides them.
Set your defaults to reflect your most common needs. Workspaces that need different treatment can be configured on their own.
## Workspace Overrides
Each workspace handles an agent in one of three ways.
| Mode | Behaviour |
| ---------------- | ---------------------------------------------------------------------------- |
| **Inherited** | Uses the organisation default exactly. This is the case for most workspaces. |
| **Configurable** | Sets its own role and settings for the agent, independent of the default. |
| **Disabled** | Turns the agent off for this workspace. No review happens. |
Keeps your configuration central and easy to manage.
A workspace handling sensitive customer data might run Data Protector as an Enforcer while the rest of the organisation observes.
Turn an agent off for a workspace where its focus is genuinely irrelevant.
## Rolling Out
A phased rollout reduces disruption and builds confidence.
Run both agents as Observers. You get full visibility into what they catch, with no impact on your team. Stay here for a week or two.
Look through [Assessments](/agents/assessments) to understand your usage. Set your Gatekeeper policy, enable the Data Protector categories that matter, and add [instructions](/agents/instructions) for the specific cases.
Move agents to Enforcer for the workspaces where the risk justifies it. Begin with your highest-risk workspaces and expand as confidence grows.
Once your defaults are stable, set workspace overrides. Stricter enforcement for high-risk teams, lighter touch elsewhere.
## Setup Checklist
| Step | Description |
| ----------------------------- | ------------------------------------------------------------------ |
| Set organisation defaults | Choose a role and settings for each agent. |
| Identify high-risk workspaces | Find the workspaces handling sensitive or regulated data. |
| Configure overrides | Use Configurable mode where a workspace needs different treatment. |
| Disable where irrelevant | Turn off an agent for workspaces it does not apply to. |
| Monitor and adjust | Review assessments regularly and refine over time. |
***
Roles, outcomes, and how verdicts are decided.
Add your own rules for specific scenarios.
# Data Protector
Source: https://docs.velatir.com/agents/data-protector
Catch sensitive content before it leaves your environment.
## What Is Data Protector?
Your team shares information with AI tools every day. Data Protector makes sure sensitive content is caught before it leaves your environment. It reviews every trace for the categories you care about and acts according to its role.
This is your primary safeguard for GDPR, data sovereignty, and privacy obligations.
Data Protector is a paid add-on. If it is not enabled for your organisation, contact us to turn it on.
## What It Catches
You choose which categories Data Protector looks for and prevents being sent.
Passwords, API keys, access tokens, private keys, and connection strings.
Information about people. Split into ordinary personal data, special-category personal data (such as health, beliefs, or biometric details), and other confidential personal information.
Card numbers, bank account details, tax identifiers, and salary information.
## Choose What It Assesses
Capabilities decide where the Data Protector looks. Choose what the agent is able to assess.
| Capability | What it assesses | |
| ------------------------ | ------------------------------------------------------- | --------- |
| **Input assessment** | The agent assesses text entered into AI services. | Always on |
| **File assessment** | The agent also assesses the contents of uploaded files. | Beta |
| **Clipboard assessment** | The agent assesses content pasted from the clipboard. | Beta |
With **Clipboard assessment** on, you can turn on [Redaction](/agents/redaction) for a category, so sensitive content is stripped from text users paste into AI tools — analysed on the device, before it is sent.
## Configure Each Category
For every category you turn on, you can set how seriously to treat it.
| Setting | What it does |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Enabled** | Turn the category on or off. |
| **Criticality** | Mark findings in the category as high criticality, so a block escalates to a person for approval. |
| **Sub-categories** | For personal data, choose ordinary, special-category, and other confidential independently. |
## Choose a Role
| Role | Behaviour |
| ------------ | ----------------------------------------------------------------------------------- |
| **Observer** | Reviews traces and flags findings for review, without notifying anyone or blocking. |
| **Enforcer** | Blocks sensitive content directly, or escalates to a person for approval. |
New Data Protectors start as Enforcer. Move to Observer first if you want to learn what it catches before you enforce.
## Tune It With Instructions
Categories cover the common cases. [Instructions](/agents/instructions) let you handle the specific ones, such as always blocking a project codename or allowing a particular scenario your team has reviewed. Instructions are grouped by category on the agent.
## When to Use Enforcer
Promote Data Protector to Enforcer when your organisation handles regulated personal data, operates in healthcare or financial services, or is subject to GDPR enforcement. The cost of a leak in these settings outweighs the occasional blocked trace. For teams handling mostly non-sensitive work, Observer gives you visibility without interruption.
***
Strip sensitive content from pasted text, on the device.
Add your own rules for specific scenarios.
Apply Data Protector across workspaces.
# Gatekeeper
Source: https://docs.velatir.com/agents/gatekeeper
Control which AI services your organisation can use, in real time.
## What Is Gatekeeper?
Gatekeeper controls which AI services your organisation can access. It enforces your default policy and any explicit exceptions, allowing or blocking services as people work. It is your access control layer for AI.
## How It Works
Gatekeeper is built from two simple parts: a **default rule** that applies to every service, and a list of **exceptions** for the services you want to treat differently. When someone reaches an AI service, Gatekeeper checks it against your policy and acts at once.
You define the policy. Gatekeeper applies it the same way for every workspace and every person.
## Choose Your Default Rule
All AI services are allowed unless you explicitly block them. You then add the services you want to **block** as exceptions. This suits organisations that want broad access with a few clear exclusions.
All AI services are blocked unless you explicitly allow them. You then add the services you want to **allow** as exceptions. This suits organisations that want a locked-down, approved-only list.
## Add Exceptions
Search the [service catalogue](/insights/service-catalog) and select the services to block or allow. Everything else follows your default rule. You can adjust the list at any time, and changes take effect on the next trace.
## Common Setups
Keep AI broadly available, but block a handful of services you do not trust or have not approved. Good for teams early in their AI adoption.
Block everything by default and allow only the services that have passed your review. Good for regulated work and strict vendor policies.
When someone reaches a blocked service, Gatekeeper can point them to an approved alternative that meets the same need.
## Working Alongside Data Protector
Gatekeeper and [Data Protector](/agents/data-protector) review each trace independently. A trace can pass Gatekeeper's service check and still be caught by Data Protector for sensitive content. Each agent adds its own layer.
***
Browse the AI services Velatir can detect.
Apply your policy across workspaces.
# Instructions
Source: https://docs.velatir.com/agents/instructions
Teach an agent how to treat a specific scenario.
## What Is an Instruction?
An instruction is a rule you give an agent: in this scenario, do this. Categories cover the common cases out of the box. Instructions let you handle the ones that are specific to your organisation, such as always blocking a project codename, or allowing a scenario your team has already reviewed.
Instructions are forward-looking. Once you add one, the agent applies it to every trace from then on.
## What an Instruction Is Made Of
| Part | Description |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Name** | A clear label, for example "Block credit card numbers (PCI)". |
| **Category** | The category it relates to, such as Personal data or Credentials. Choose **Other** if none fit. |
| **Trigger** | When the instruction should apply. |
| **Criticality** | Low or High. High criticality escalates to a person. |
| **Action** | What the agent does in this scenario: Allow, Block, or Escalate. |
## Triggers
The trigger decides when an instruction applies. Pick the approach that fits the rule.
Matches a scenario by meaning, even when the wording differs. Describe the situation in plain language.
*Example:* "Customer is discussing their account balance or transaction history."
Matches a precise pattern. The fastest and most exact option, and best for structured data such as card numbers or reference codes.
*Example:* a pattern for a 13 to 16 digit card number.
Matches an exact list of terms. Best for known codenames, vendor names, or product identifiers.
*Example:* "Project Aurora".
## Create an Instruction
Go to **Agents → Instructions** and start a new instruction.
Name it, pick a category, and choose the trigger that matches the rule.
Choose Low or High criticality, then the action: Allow, Block, or Escalate.
Assign the instruction to the agent that should use it. Instructions appear grouped by category on the agent.
## Save an Instruction From an Assessment
You do not have to write every instruction from scratch. When you review an [assessment](/agents/assessments) and decide how a scenario should be treated in future, you can save it as an instruction directly from that decision. The new instruction keeps a link back to the assessment it came from, so you always know where it originated.
***
Review verdicts and save instructions from them.
See how instructions sit alongside categories.
# Redaction
Source: https://docs.velatir.com/agents/redaction
Strip sensitive content from pasted text on the device, before it reaches an AI tool.
## What Is Redaction?
Redaction is a [Data Protector](/agents/data-protector) capability. When someone pastes content into a supported AI tool, Data Protector analyses the pasted text **on the device** and removes anything that matches the categories you protect, then lets the person decide how to proceed. The sensitive content is stripped before it reaches the AI service.
Because the analysis runs locally, this is different from a normal assessment: the pasted content is **never sent to Velatir**. The sensitive content stays out of the AI service without the paste becoming a dead end.
Redaction is in **beta** and, for now, applies to **pasted content** in supported AI tools. It builds on the **Clipboard assessment** capability and takes effect only when the Data Protector is an **Enforcer**. It runs through [Velatir for Desktop](/desktop-app/overview) and the browser extension.
## How It Works
A user pastes text into a supported AI tool in the browser.
Data Protector inspects the pasted text locally, against the categories you have turned Redaction on for. Nothing is sent to Velatir for this step.
The user sees a redacted version, with matched content replaced by placeholders, and chooses how to proceed. Only their chosen result continues to the AI tool.
## What Gets Redacted
Redaction acts on the same [categories](/agents/data-protector#what-it-catches) the Data Protector already protects — Credentials, Personal data, and Financial data. You choose which of them to redact from pasted text; there is no separate list to maintain. Turn Redaction on for a category and its sensitive content is stripped on paste.
## Turn On Redaction
Redaction only acts under **Enforcer**. An [Observer](/agents/data-protector#choose-a-role) assesses but never changes content, so an Observer Data Protector will not redact anything.
In the Data Protector's **Capabilities**, turn on **Clipboard assessment**. Until it is on, the Redaction switch stays disabled.
For each category you want removed from pasted text, flip its **Redaction** switch.
Redaction runs through Velatir for Desktop and the browser extension. It requires **Velatir for Desktop 0.20.0** or later and the **browser extension 1.11.0** or later. Velatir for Desktop updates itself automatically, so managed devices pick this up without action.
The dashboard lets you switch Redaction on for a category even when the Data Protector is an Observer, but an Observer never changes content — nothing will be redacted until you promote it to **Enforcer** and enable **Clipboard assessment**.
## What the User Sees
When Redaction is active, pasting sensitive content into a supported AI tool shows the user a redacted version of what they pasted, with the matched content replaced by placeholders. The user reviews it and decides how to proceed — so sensitive content is kept out of the AI service, while ordinary pastes continue uninterrupted.
## Privacy
Redaction is designed to keep sensitive content on the device. The pasted text is analysed and redacted **locally**, and — unlike a standard assessment — is **not sent to Velatir's backend**. Only the result the user chooses to send continues to the AI tool. See [Data privacy](/security/data-privacy) for how Velatir handles content more broadly.
***
The agent Redaction belongs to, and the categories it protects.
Apply the Data Protector across workspaces.
What Velatir stores, and how it scrubs sensitive content.
The client that runs Redaction on the device.
# Understanding Agents
Source: https://docs.velatir.com/agents/understanding-agents
How Velatir's agents review every trace and decide what happens next.
## What Are Agents?
Agents are the heart of Velatir. They review every trace that flows through your organisation and decide whether it should be allowed, flagged, blocked, or escalated. You do not trigger them by hand. They work in real time, applying the configuration you have set.
Velatir has two agents, and they work together. A single trace can be reviewed by both at once, each from its own angle.
Controls which AI services your organisation can use. It enforces your default policy and any explicit exceptions, allowing or blocking services as people work.
Catches sensitive content before it leaves your environment, across credentials, personal data, and financial data.
## Roles
Every agent runs with a **role** that sets how much authority it has. The role decides what actually happens when an agent has a concern.
The agent reviews traces and flags its findings for review. It does not notify anyone or block anything.
**Best for:** the first weeks of a rollout, lower-risk workspaces, and building a picture of your usage before you enforce anything.
The agent blocks traces that break your rules, or escalates them to a person for approval before they proceed.
**Best for:** workspaces handling sensitive data, regulated work, and any case where a violation must be prevented.
## Outcomes
When an agent reviews a trace, the result is one of four outcomes. Which one you see depends on the agent's role and what it found.
| Outcome | What it means |
| ------------- | --------------------------------------------------------- |
| **Allowed** | No concern. The trace proceeds. |
| **Flagged** | An Observer noted a finding for review, without blocking. |
| **Blocked** | An Enforcer stopped the trace. |
| **Escalated** | The trace was sent to a person for review or approval. |
## How an Outcome Is Decided
Both active agents review the trace at the same time, each recording its own assessment.
An Observer only flags. An Enforcer can block, or escalate for approval.
If either agent blocks, the trace is blocked. If either escalates, it is escalated. The trace proceeds only when nothing stands in its way.
Start both agents in Observer to learn what they catch, then promote to Enforcer where the risk justifies it. See [Configuring agents](/agents/configuring-agents).
***
Teach an agent how to treat a specific scenario.
Review every verdict an agent has reached.
# Claude Cowork
Source: https://docs.velatir.com/connectors/claude-cowork
Send Claude Cowork activity to Velatir by pointing Cowork's OpenTelemetry export at your organisation's Velatir endpoint
Claude Cowork can export its activity over OpenTelemetry. Point that export at Velatir and Cowork sessions
appear alongside everything else in your organisation.
This is configured once, for the whole organisation, in Anthropic's admin settings — there is nothing to
install on anyone's machine.
Cowork monitoring requires a Claude Team or Enterprise plan.
**Cowork is set up in the opposite direction to most connectors.** Elsewhere you give Velatir a credential and
Velatir fetches your activity. Here you give *Claude* a Velatir endpoint and Cowork sends its activity to us.
So there is nothing to add on the Velatir side — you will not find Cowork in the connector list, and all the
configuration below happens in Claude.
## What you need
* Administrator access to your Claude organisation's admin settings.
* Your Velatir ingest key. Create one under **Settings → API keys**, or see the [quickstart](/quickstart).
## Connect Cowork
In Claude, go to **Organization Settings → Cowork** and find the **Monitoring** section.
Set **OTLP endpoint** to:
```
https://otlp.velatir.com
```
Enter it exactly as shown, with no path after the domain — Cowork adds the rest itself.
Set **OTLP protocol** to either `http/protobuf` or `http/json`. Velatir accepts both, so pick either one.
Set **OTLP headers** to your ingest key:
```
X-API-Key=vltr_your_key_here
```
`Authorization=Bearer vltr_your_key_here` also works if you prefer it.
Velatir needs nothing here. Cowork already identifies itself in every message it sends, so there is no
label to add.
If your organisation uses resource attributes for its own purposes, anything you put here is passed
through and ignored — with one exception:
Do not set `service.name`. That is how Velatir recognises the activity as coming from Cowork. Overriding
it means your activity arrives unrecognised and is discarded.
Save your settings and start a **new** Cowork session. Cowork reads these settings when a session begins,
so sessions already running keep using the old configuration.
Activity from that new session appears in Velatir within a minute or two.
## What Velatir receives
Cowork sends prompts, model responses, tool use, and errors. Whether the **text** of prompts and responses is
included is controlled on the Claude side, not by Velatir. When Claude sends activity without that text,
Velatir records nothing for those turns rather than storing empty entries.
Cowork also sends usage measurements. Velatir accepts them and does not store them.
## Notes
* **No firewall changes are needed for Cowork itself.** Cowork adds your collector's hostname to its own
session network allowlist automatically. If your corporate network restricts outbound traffic from
employees' machines, allow `otlp.velatir.com` on port 443 there.
* **Your ingest key identifies your organisation.** Anyone holding it can send activity as your organisation,
so treat it like any other credential. Rotate it under **Settings → API keys** if it is exposed.
* **Cowork sessions carry the acting user's email**, so activity is attributed per person without any extra
configuration.
## Troubleshooting
Start a brand-new Cowork session — settings only take effect for sessions started after you saved them.
Then check the endpoint is `https://otlp.velatir.com` with nothing after the domain, and that the header
is spelled `X-API-Key=` followed by your key with no spaces around the `=`.
That text is only included when content capture is enabled on the Claude side. Velatir stores whatever
Cowork sends and never invents the rest.
Confirm the key is active under **Settings → API keys**. A revoked or expired key stops working
immediately, and Cowork has no way to show you the rejection — you will simply see no new activity.
## Related
Set up your account and create a key
How activity is grouped once it reaches Velatir
# Core Concepts
Source: https://docs.velatir.com/core-concepts
The key parts of the Velatir platform and how they fit together.
## The Building Blocks
Velatir is built around a small set of concepts. Once these click, the rest of the platform follows.
Your organisation is the top-level account. Workspaces sit inside it and separate activity by team, department, or project.
Every AI interaction is captured as a trace. Related traces are grouped into a session that represents a complete conversation or workflow.
Gatekeeper and Data Protector review every trace. Gatekeeper controls which services can be used, and Data Protector catches sensitive content.
Each agent records an assessment for every trace it reviews, with the verdict and the reasoning behind it.
Your own rules that tell an agent what to do in a specific scenario, such as always blocking a project codename.
Aggregated views of how your organisation uses AI, where activity concentrates, and what agents are catching.
## How They Fit Together
An AI interaction, in the browser or a desktop app, is captured and sent to Velatir as a trace. Each trace has a direction: **Inlet** (a request to an AI service), **Response** (a reply from it), or **Signal** (an event). Related traces are grouped into a session.
Your active agents review the trace at the same time. Each one records an assessment and reaches a verdict, applying your categories and instructions.
The verdict depends on each agent's role. An Observer flags its findings for review. An Enforcer can block the trace or escalate it for approval. The most restrictive outcome wins.
If a trace is escalated, it is sent to your connected channels so the right people can respond.
The trace, each assessment, and the outcome are recorded for audit purposes.
## Key Principles
### Traces are the foundation
Every AI interaction is captured as a trace. This gives your organisation full visibility into AI usage.
### Agents handle the volume
Agents review every trace automatically. People only see what an agent flags or escalates.
### Roles control authority
Each agent runs as an Observer or an Enforcer. You can start with monitoring only and add enforcement as you build confidence.
### Instructions tune behaviour
Instructions let you teach an agent how to treat a specific scenario, so its verdicts match your organisation over time.
### Everything is auditable
Every trace, assessment, decision, and outcome is logged with full context. Your compliance trail is always complete.
## Organisation and Workspaces
| Concept | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Organisation** | Your company account. Holds members, settings, agent defaults, and your subscription. |
| **Workspace** | A space within your organisation for a team, department, or project. Workspaces can nest, and each has its own activity. |
| **Organisation roles** | **Administrator** (full access) and **Reader** (view only). |
| **Workspace roles** | **Admin**, **Editor**, and **Reader**, with progressively fewer permissions. |
See [Roles & permissions](/platform/roles-and-permissions) for the full breakdown.
## Trace Directions
| Direction | Description | Example |
| ------------ | -------------------------------------- | -------------------------------------------- |
| **Inlet** | A request going to an AI service | Someone submits a prompt to a chat assistant |
| **Response** | A reply coming back from an AI service | The assistant's answer |
| **Signal** | A related event | A session starting, or a background event |
## Assessment Outcomes
| Outcome | What it means |
| ------------- | --------------------------------------------------------- |
| **Allowed** | The agent had no concern. The trace proceeds. |
| **Flagged** | An Observer noted a finding for review, without blocking. |
| **Blocked** | An Enforcer stopped the trace. |
| **Escalated** | The trace was sent to a person for review or approval. |
***
Meet Gatekeeper and Data Protector.
Follow a trace from capture to final state.
# Bring Your Own Certificate
Source: https://docs.velatir.com/desktop-app/bring-your-own-ca
Use your organisation's certificate authority as the authority Velatir uses to inspect AI traffic
## Overview
By default Velatir generates a unique certificate authority on each device. Organisations that already run an internal CA can supply their own instead, so managed devices do not need to trust a new root. For pilots, the default Velatir CA is the simpler choice.
## What to Provide
A **PFX (PKCS#12)** bundle containing the CA certificate, its private key, and any intermediates needed to chain to a root your devices trust. The private key stays on the device and never leaves it.
The certificate must be a CA (`keyUsage` including `keyCertSign` and an appropriate `basicConstraints` extension). A leaf certificate will not work, because Velatir issues per-host certificates from it.
## Single-Device Setup
For evaluation on one device, use the CLI:
```bash theme={null}
velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password'
```
Verify the change took effect. `get-config` lists the active certificate fingerprint; `status` confirms the new authority is in use.
```bash theme={null}
velatir get-config
velatir status
```
## Organisation-Wide Setup
Deploy the PFX bundle from your MDM platform first, then deploy the desktop client with the bundle path in the install command.
### Windows (Intune)
1. Deploy the PFX to a known path (for example, `C:\ProgramData\Velatir\byo-ca.pfx`) using an Intune file policy.
2. Point the MSI at it:
```
/qn INGEST_KEY="vltr_..." VELATIR_BYO_CA_PATH="C:\ProgramData\Velatir\byo-ca.pfx" VELATIR_BYO_CA_PASSWORD=""
```
### macOS (Jamf Pro)
1. Deploy the PFX via a Jamf file payload (for example, `/Library/Application Support/Velatir/byo-ca.pfx`).
2. In the ingest-key staging script, also call:
```bash theme={null}
/usr/local/bin/velatir set-ca \
--path "/Library/Application Support/Velatir/byo-ca.pfx" \
--password ""
```
See [Enterprise deployment](/desktop-app/enterprise-deployment) for the full Intune and Jamf Pro flow.
## Rotating the Certificate Authority
Deploy the new PFX to the same path and redeploy the install command, or rerun `set-ca`. For lower risk, roll out group by group:
1. Stage the new CA in a small device group.
2. Confirm `velatir status` shows the new fingerprint and interactions still reach the dashboard.
3. Expand the rollout.
Rotation restarts capture, so one in-flight interaction may produce a single failed trace. Plan rotations during low-activity periods if that matters.
## Removing the Custom Certificate Authority
To revert to the Velatir-issued CA:
```bash theme={null}
velatir set-ca --path '' --password ''
```
## Verification
After installing or rotating, confirm supported applications still see a valid certificate chain:
```bash theme={null}
velatir logs --host -f
```
Trigger an interaction in a supported AI application; the log should show a successful connection on the new authority. If applications report certificate errors, see [Troubleshooting](/desktop-app/troubleshooting#certificates).
## Next Steps
The Intune and Jamf Pro flows that wrap bring-your-own-CA distribution.
How the desktop client handles certificates at install time.
Detail on the `set-ca` and `get-config` commands.
Diagnose certificate trust issues after a rotation.
# CLI Reference
Source: https://docs.velatir.com/desktop-app/cli
Control the Velatir desktop client from the command line: status, start and stop, updates, logs, and configuration
## Overview
The `velatir` command is installed on the system path by the Windows MSI and the macOS package. It is the supported way to control and script the desktop client.
## At a Glance
| Command | Requires admin | Purpose |
| ------------------------------- | -------------- | -------------------------------------------------------- |
| [`status`](#status) | No | Show agent and host state. |
| [`start`](#start) | Yes | Activate AI traffic capture. |
| [`stop`](#stop) | Yes | Deactivate AI traffic capture. |
| [`restart`](#restart) | Yes | Stop then start. |
| [`hide`](#hide) | Yes | Hide the system-tray icon. |
| [`show`](#show) | Yes | Show the system-tray icon. |
| [`update`](#update) | No / Yes | Check for updates, or apply with `--apply`. |
| [`host restart`](#host-restart) | Yes | Restart Velatir's capture process. |
| [`quit`](#quit) | Yes | Stop the agent itself. |
| [`events`](#events) | No | Stream agent events. |
| [`logs`](#logs) | No | Tail the agent or host log. |
| [`health`](#health) | No | Show interception-stack health and any failing checks. |
| [`test`](#test) | No | Send a synthetic trace to verify the install end to end. |
| [`version`](#version) | No | Show CLI, agent, and host versions. |
| [`get-config`](#get-config) | No | Show effective configuration. |
| [`set-api-key`](#set-api-key) | Yes | Update the Velatir ingest key. |
| [`set-ca`](#set-ca) | Yes | Provide a bring-your-own CA. |
## Global Flags
| Flag | Effect |
| ----------------- | -------------------------------------------------------- |
| `--help`, `-h` | Print usage. Also accepted as the `help` subcommand. |
| `--version`, `-v` | Alias for `version`. |
| `--json` | Emit JSON output where applicable. Useful for scripting. |
## Exit Codes
| Code | Meaning |
| ---- | --------------------------------- |
| `0` | Success |
| `1` | Agent unreachable |
| `2` | Administrator privileges required |
| `3` | Operation failed |
| `64` | Invalid usage |
## Control Commands
### status
Show the current state of the desktop client: version, uptime, whether capture is running, and the last update check. Add `--json` for a structured result.
```bash theme={null}
velatir status
```
### start
Activate AI traffic capture.
```bash theme={null}
velatir start
```
### stop
Pause AI traffic capture without uninstalling. The client keeps running but stops capturing.
```bash theme={null}
velatir stop
```
### restart
Stop then start. Velatir re-binds on its own when the network changes, so a restart is only a manual fallback. See [VPN compatibility](/desktop-app/vpn-compatibility).
```bash theme={null}
velatir restart
```
## Tray Icon
### hide
Hide the system-tray icon. It stays hidden across restarts; capture continues normally. To hide it from install, use the `VELATIR_HIDE_TRAY` MSI property; see [Enterprise deployment](/desktop-app/enterprise-deployment#msi-properties-windows).
```bash theme={null}
velatir hide
```
### show
Show the tray icon again.
```bash theme={null}
velatir show
```
## Update Commands
### update
Check whether a newer version is available (does not download).
```bash theme={null}
velatir update
```
Add `--apply` to install and relaunch the new version immediately. Use this to force an update before the regular poll picks it up.
```bash theme={null}
velatir update --apply
```
### host restart
Restart Velatir's capture process. It comes back within 30 seconds. Useful after a configuration change that needs a reload.
```bash theme={null}
velatir host restart
```
### quit
Stop the desktop client. It will not restart on its own; it stays stopped until its service starts again (next boot, or `sc start VelatirAgent` on Windows) or you launch it manually.
```bash theme={null}
velatir quit
```
## Observability Commands
### events
Stream the client's event log. Filter by event type with `--filter`.
```bash theme={null}
velatir events
velatir events --filter UpdateAvailable
```
### logs
Tail the agent or host log. Useful when diagnosing why traces are not appearing for an application.
```bash theme={null}
velatir logs # Agent log
velatir logs --host # Host log
velatir logs -f # Follow mode (like tail -f)
```
### version
Show the CLI, agent, and host versions.
```bash theme={null}
velatir version
```
### health
Show current health and the reason and fix for any failing check. Exits `0` when healthy and non-zero when degraded, so it works as a monitoring probe. See [Health checks](/desktop-app/health-checks).
```bash theme={null}
velatir health
velatir health --json
```
### test
Run a one-shot, end-to-end check of the install.
```bash theme={null}
velatir test
```
Sends a synthetic trace and prints the result. Success confirms the whole chain works: the client is running, the ingest key is valid, and the backend is reachable. It exits non-zero with a reason when something is wrong.
## Configuration Commands
### get-config
Show the effective configuration. The ingest key is masked.
```bash theme={null}
velatir get-config
```
### set-api-key
Update the Velatir ingest key. Velatir restarts so the new key takes effect immediately; pass `--no-restart` to skip the restart.
```bash theme={null}
velatir set-api-key --key vltr_your_api_key_here
```
### set-ca
Provide a bring-your-own certificate authority. The file must be a PFX (PKCS#12) bundle. Velatir restarts so it takes effect immediately; pass `--no-restart` to skip the restart. See [Enterprise deployment](/desktop-app/enterprise-deployment) for the recommended distribution pattern.
```bash theme={null}
velatir set-ca --path /path/to/internal-ca.pfx --password 'your-pfx-password'
```
## Common Recipes
### Verify the install end to end
```bash theme={null}
velatir status
velatir test
```
`velatir test` confirms the client, ingest key, and backend are all working. To watch live capture instead, run `velatir logs --host -f` and trigger an interaction in a supported AI application.
### Rotate the ingest key
```bash theme={null}
velatir set-api-key --key vltr_new_key
velatir status
```
Confirm with `status` that the masked key has changed.
### Force the latest version
```bash theme={null}
velatir update --apply
velatir version
```
### Re-bind after a VPN change
Only needed as a manual fallback; Velatir re-binds on its own when the network changes. See [VPN compatibility](/desktop-app/vpn-compatibility).
```bash theme={null}
velatir restart
```
## Next Steps
Resolve agent-unreachable errors and other common issues.
Drive the CLI from MDM and scripted rollouts.
Understand what the desktop client does.
Quick answers to the questions that come up most often.
# Directory Context
Source: https://docs.velatir.com/desktop-app/directory-context
Attach department, office, and group context to traces by granting Velatir admin consent in Microsoft Entra
Velatir for Desktop can attach organisational context to every trace: the person's department, office, and group memberships. This routes activity to the right workspace and keeps your team-level [insights](/insights/overview) accurate. End users see nothing; there is no prompt and no per-user setup.
On Microsoft Entra this needs a one-time admin consent, so Velatir can read directory profiles. Without it, traces are still captured; they simply carry no directory context.
## Grant admin consent
1. As a Microsoft Entra administrator, open this URL in your tenant:
```
https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=ddddc2f1-9b3e-4ca2-99bf-99cbae699402&scope=https://graph.microsoft.com/.default&redirect_uri=https://docs.velatir.com/setup/directory-context
```
2. Sign in and review the request. It asks for one read-only permission, **Sign in and read user profile** (`User.Read`):
| Field | Value |
| ----------- | ------------------------------------------- |
| Application | Velatir LDAP host |
| Publisher | ldap.velatir.com |
| Permission | Sign in and read user profile (`User.Read`) |
Select **Consent on behalf of your organisation** and accept.
3. The app now appears under **Entra → Enterprise applications → Velatir LDAP host**. Open it there to confirm admin consent is granted (use **Grant admin consent for \[your organisation]** if it is not). You can review the permission, see sign-in activity, or revoke access from the same place at any time.
That is the whole setup. Directory context starts flowing once consent is granted.
For on-premise Active Directory without Entra, this step is not required: Velatir reads directory details locally. For hybrid setups, grant consent anyway so context still resolves when people work off the corporate network.
# Download and Install
Source: https://docs.velatir.com/desktop-app/download-and-install
Install Velatir for Desktop on a single Windows or macOS device in a few minutes
Velatir for Desktop ships as a small installer. At first run it downloads the rest of the app and then keeps itself up to date, so this is the only step you take on the device.
Rolling out to a fleet? See [Enterprise deployment](/desktop-app/enterprise-deployment) for Microsoft Intune, Jamf Pro, and other MDM platforms.
## Build your install command
Enter your ingest key, pick your platform, and copy the command. Generate a key on the **Setup** tab of the [Velatir dashboard](https://app.velatir.com).
## Requirements
| Requirement | Detail |
| ---------------- | ---------------------------------------------------------------------------------- |
| Operating system | Windows 10 or 11 (x64, arm64), or macOS 13 Ventura or later (Apple Silicon, Intel) |
| Access | Administrator rights on the device |
| Network | Outbound HTTPS to `api.velatir.com` and Velatir's update storage |
## Updates and uninstall
The agent checks for new versions every four hours and applies them automatically, so there is no update service to manage. On Windows, the background process runs as the `VelatirAgent` service. To apply an update immediately, run `velatir update --apply`. The previous version stays on disk until the new one is confirmed running, so there is no in-between state.
**Windows.** Remove from **Settings → Apps → Installed apps**, or run `msiexec /x` with the product code. This removes the agent, the host, the `VelatirAgent` service, the network adapter, and the Velatir certificate.
If the uninstall is interrupted, your MDM cannot remove the app, or items remain afterwards, see [Uninstall cleanup](/desktop-app/uninstall-cleanup). Devices on a version older than the current installer can also leave artefacts a standard uninstall does not clear.
**macOS.** Run the bundled uninstaller:
```bash theme={null}
sudo velatir-uninstall
```
It removes the app, the background services, the system extension, and the Velatir certificate. A restart completes removal of the system extension.
**Using Firefox?** After uninstalling, the Velatir extension may still appear in Firefox. This is expected — and not something the uninstaller can fix. Unlike Chrome and Edge, which automatically remove an extension that was installed by policy, Firefox leaves a policy-installed extension in place (it becomes inactive once Velatir is gone). To remove it, open Firefox → **Menu → Add-ons and themes → Extensions**, click the **⋯** next to Velatir, and choose **Remove**. If **Remove** is greyed out, restart Firefox first so it picks up the change.
## Next steps
Roll out silently across your fleet with Intune, Jamf, or any MDM.
What the installer asks for, and why.
Resolve common install and first-run issues.
The architecture behind the app.
# Enterprise Deployment
Source: https://docs.velatir.com/desktop-app/enterprise-deployment
Roll Velatir for Desktop out across your fleet with Microsoft Intune, Jamf Pro, or any MDM
Velatir for Desktop is a standard MSI (Windows) and PKG (macOS), so any MDM that deploys those works. One ingest key configures everything: no per-feature flags, no per-customer builds.
## Build your install command
Generate an ingest key on the **Setup** tab of the [Velatir dashboard](https://app.velatir.com). The same key works for every device.
## Deploy with your MDM
1. Go to **Apps → All apps → Add**, choose **Line-of-business app**, and upload the MSI from the builder above.
2. Under **App information → Command-line arguments**, paste the Intune arguments from the builder.
3. Assign to your device groups in **Required** mode. Intune handles elevation.
To rotate the key later, update the command-line arguments and redeploy.
1. Upload the PKG from the builder under **Packages** and deploy it with a policy scoped to your Macs (**Recurring Check-in**, **Once per computer**).
2. Add a configuration profile, scoped to the same Macs, with two payloads:
* **Application & Custom Settings** → preference domain `com.velatir.agent`, key `ApiKey` set to your ingest key. This is the macOS equivalent of the MSI's `INGEST_KEY`; update it later to rotate the key with no reinstall.
* **System Extensions** → allow Team Identifier `AA7QLU3S4R` (Network Extension), so the agent activates with no end-user prompt.
Use the **macOS app (PKG)** app type — not **Line-of-business app**. Velatir installs a background agent under `/Library`, not an application in `/Applications`, and the line-of-business type cannot deploy or detect a package of that shape.
1. Go to **Apps → All apps → Create**, choose the **macOS** platform, select **macOS app (PKG)**, and upload the PKG from the builder above.
2. On **Detection rules**, set **Ignore app version** to **Yes**, then clear **Included apps**: remove the `com.velatir.agent.bootstrap` entry Intune fills in automatically. That is the package identifier, not an application, so while it is listed the app can never report as installed. If Intune will not save an empty list, use bundle ID `com.velatir.desktopapp` instead.
3. On **Requirements**, set the minimum operating system to **macOS 13.0**.
4. Assign to your device groups in **Required** mode.
5. In **Devices → Configuration**, add a **Preference file** profile scoped to the same devices, with preference domain `com.velatir.agent` and this property list:
```xml theme={null}
ApiKey
vltr_your_ingest_key
```
The key must be named `ApiKey`. `INGEST_KEY` is the Windows MSI property and has no effect in a configuration profile. Update this value later to rotate the key with no reinstall.
6. Add a profile with a **System Extensions** payload allowing Team Identifier `AA7QLU3S4R`, so the agent activates with no end-user prompt.
Two things to settle before you assign it:
* The **Microsoft Intune management agent for macOS** (2308.006 or later) must be on the devices — it is what runs the installer. Configuration profiles arrive over a different channel, so a profile that applies cleanly is no evidence that the app can install.
* Velatir ships one package per architecture and no universal build. Add the Apple Silicon and Intel packages as two apps, each assigned to a group of matching devices.
Confirm a rollout with `velatir status` on a device, or from the **Devices** view in the dashboard, rather than from the Intune console alone. Because the package installs no application bundle, Intune has limited ability to detect it and may keep reporting an unknown state on devices that are installed and reporting normally. See [Intune reports the app state is unknown](/desktop-app/troubleshooting#fleet-and-mdm).
Any tool that runs `msiexec` (Windows) or `installer` (macOS) works: use the command from the builder above. For a Windows detection rule, check for the `VelatirAgent` service or the install path `C:\Program Files\Velatir\`.
macOS never installs a certificate through MDM: Velatir generates a unique CA on each device, so there is no shared root to distribute.
## Removing Velatir from a fleet
Change the assignment first, on either platform. While the app is still assigned as **Required**, Intune reinstalls it behind the removal and the devices look unchanged.
**Windows.** Set the app assignment to **Uninstall**. If devices do not come off — the assignment reports a failure, or the app stays listed — deploy the cleanup script in [Uninstall cleanup](/desktop-app/uninstall-cleanup) as an Intune remediation script running as SYSTEM. It needs no detection rule, so a rule that never matches cannot block the removal, and it reports leftovers through its exit code.
**macOS.** The **macOS app (PKG)** app type has no **Uninstall** assignment, so remove the assignment instead. That stops Intune reinstalling Velatir but does not take it off the devices — run the bundled uninstaller as a shell script under **Devices → Scripts**, as root:
```bash theme={null}
sudo velatir-uninstall
```
Devices need a restart to finish removing the system extension.
## Reference
| Property | Required | Description |
| ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `INGEST_KEY` | Recommended | Stages the ingest key at install time. Hidden from MSI logs. (`VELATIR_API_KEY` is accepted as a deprecated alias.) |
| `VELATIR_HIDE_TRAY` | No | Set to `1` to hide the system-tray icon. Windows only; on macOS use `velatir hide`. `velatir show` reverses it at runtime. |
| `VELATIR_BYO_CA_PATH` | No | Path to a PFX bundle for bring-your-own-CA installs. |
| `VELATIR_BYO_CA_PASSWORD` | No | Password for the PFX bundle above. |
**Windows.** Redeploy with the new key in the command-line arguments. The host restarts and picks it up.
**macOS.** Update the `ApiKey` value in the `com.velatir.agent` managed preference in your MDM. Devices apply it on the next check-in, with no reinstall.
Run `velatir status --json` as a Microsoft Intune Remediation or a Jamf Pro extension attribute. It reports client state, version, and the last trace timestamp, so you can spot drift across the fleet from your dashboard.
Velatir auto-updates by default. To coordinate updates with your own change-management process, contact support to enable a per-tenant update channel.
Supply your own certificate authority instead of the Velatir-issued one. See [Bring your own certificate](/desktop-app/bring-your-own-ca) for the format, distribution, and rotation.
## Next steps
What the installer asks for on each platform.
Monitor agent and capture health across the fleet.
Behaviour alongside corporate VPNs.
Diagnose failures during scaled rollouts.
# FAQ
Source: https://docs.velatir.com/desktop-app/faq
Answers to the most common questions about Velatir for Desktop
## Overview
The most common questions we hear about Velatir for Desktop, grouped by topic. If your question is not here, [Troubleshooting](/desktop-app/troubleshooting) covers diagnosis, and your account team can help with anything operational.
## What it is and what it does
Yes. Velatir for Desktop covers AI usage in web apps as well as in desktop and CLI apps, from one install and one ingest key. There is no separate product to deploy.
No. Velatir only inspects traffic from a curated list of supported AI applications. Everything else on the device is passed through untouched.
Coverage includes GitHub Copilot (VS Code, JetBrains Rider, IntelliJ IDEA, Visual Studio, Xcode, Neovim, GitHub Copilot CLI), Microsoft Copilot in Word, Excel, PowerPoint, Outlook, and Teams, the standalone Microsoft Copilot desktop app, Claude Code (CLI and VS Code), Claude Desktop, Claude for Word, and ChatGPT for Word. See the [supported applications](/desktop-app/overview#supported-applications) list for the current set. If you need coverage for an application that is not yet supported, request it through your account team.
## Installation and updates
An MSI for Windows and a PKG for macOS. Linux support is in development. See [Download and install](/desktop-app/download-and-install).
Yes. Microsoft Intune, Jamf Pro, and any MDM that deploys an MSI or PKG work out of the box. See [Enterprise deployment](/desktop-app/enterprise-deployment).
The agent checks every four hours and updates itself automatically, with no update service to manage. You can apply one immediately with `velatir update --apply`.
Yes. Tenant-specific update channels are available for organisations that need to coordinate updates with their own change-management process. Contact support to enable this for your tenant.
Use Add/Remove Programs on Windows (or `msiexec /x`), and `sudo velatir-uninstall` on macOS. See [Download and install](/desktop-app/download-and-install#updates-and-uninstall).
Two things that route around it. On macOS with Firefox, the browser extension may remain listed after uninstall (it is inactive) and needs removing by hand. And if the uninstall is interrupted, your MDM cannot remove the app, or items remain afterwards, run the cleanup script in [Uninstall cleanup](/desktop-app/uninstall-cleanup) — devices on a version older than the current installer can leave artefacts a standard uninstall does not clear.
## Permissions and privacy
Administrator rights at install time on both platforms, and a one-time system extension approval on macOS. The full list with rationale is in [Permissions](/desktop-app/permissions).
Velatir does not monitor your clipboard, screen, microphone, or files. It does not request Full Disk Access on macOS, and it does not capture screenshots or keystrokes. Its inputs are the connections of supported AI applications, with one exception: if your organisation turns on [Redaction](/agents/redaction), the browser extension reads the text you paste into a supported AI tool so it can be analysed and redacted on the device before it is sent. That content is processed locally and is never sent to Velatir.
Only when your organisation enables it. With [Redaction](/agents/redaction) on, the text you paste into a supported AI tool is passed to an on-device component that strips sensitive content. The analysis runs entirely on the device — the pasted content is never sent to Velatir — and you see the redacted result before anything reaches the AI tool.
For each captured interaction, a trace containing the prompt, the response, the model, token counts, and process context. What gets stored after capture is governed by your agent configuration and your data privacy settings. See [Data privacy](/security/data-privacy).
Velatir needs to reach `api.velatir.com` to submit traces. If the device is offline it buffers them and sends once connectivity returns; your AI applications keep working as normal in the meantime.
## Networking
Yes, including split-tunnel and full-tunnel VPNs. Velatir adjusts on its own when a VPN connects or disconnects, so no restart is needed. See [VPN compatibility](/desktop-app/vpn-compatibility).
Velatir recovers on its own within seconds, and never leaves the device without internet access.
## Certificates
Yes. Provide a PFX bundle and Velatir uses it instead of its own certificate. This is the recommended path if you already operate an internal CA. See [Bring your own certificate](/desktop-app/bring-your-own-ca).
Runtimes that keep their own trust store (Node.js, Python `requests`, JVM) need an explicit pointer to the Velatir certificate. See [Troubleshooting](/desktop-app/troubleshooting#certificate-not-trusted-by-a-specific-runtime).
Pinned applications are detected and passed through unmodified; they cannot be inspected without the application cooperating. If a pinned application matters to your compliance workflow, contact your account team.
## Operations
Run `velatir status --json` as a Microsoft Intune Remediation, a Jamf Pro extension attribute, or any similar device-state collector. The output includes the agent's status, version, capture state, and last trace timestamp.
Redeploy the install command with the new key, or run `velatir set-api-key --key vltr_...` on the device. The new key takes effect immediately.
Nothing visible besides a tray icon. Supported AI applications work exactly as before, and users are not prompted during normal use. Behaviour changes only when an agent in **Enforcer** mode acts — for example blocking or escalating an interaction, or, when [Redaction](/agents/redaction) is enabled, showing a redacted version of pasted content for the user to review.
## Next steps
Set Velatir up on Windows or macOS.
Roll out across your organisation.
Diagnose the issues most commonly seen in production.
How Velatir for Desktop works.
# Health Checks
Source: https://docs.velatir.com/desktop-app/health-checks
How the Velatir desktop client monitors itself, and how to read velatir health
## Overview
Velatir checks its own health every \~30 seconds. If something breaks it never blocks your traffic: it either pauses capture or steps aside so connections flow directly, then recovers on its own once the problem clears. Read the current state with [`velatir health`](/desktop-app/cli#health).
## States
| State | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Ok` | Everything is working; AI apps are being captured. |
| `DegradedInspection` | Capture is paused (for example, the certificate is not trusted). Apps keep working, but AI activity may not be traced until it clears. |
| `DegradedRouting` | The capture path itself broke. Velatir steps aside so traffic flows directly, uninspected, until it clears. |
## Reading `velatir health`
```bash theme={null}
velatir health
```
```text theme={null}
Health: DegradedRouting
Evaluated: 2026-06-05 14:31:02 (8s ago)
Checks:
[ ok ] api-healthz-e2e
[ ok ] cert-trusted
[FAIL] windows-routing
reason: traffic capture path is not running
action: step out of the path
```
Each failing check shows a reason and the action Velatir took. The exit code is `0` when healthy and non-zero when degraded, so the command works as a monitoring probe. Add `--json` for the raw snapshot.
## If it shows a problem
A degraded state usually clears on its own. If it persists:
* **Certificate not trusted:** see [Troubleshooting → Certificates](/desktop-app/troubleshooting#certificates).
* **macOS extension not enabled:** approve it in **System Settings → General → Login Items & Extensions → Network Extensions**.
* **Anything else:** run `velatir logs --host -f`, reproduce, and share the output with support.
## Next Steps
Resolve a degraded state.
The `health` and `test` commands in detail.
# How It Works
Source: https://docs.velatir.com/desktop-app/how-it-works
How Velatir for Desktop captures AI usage, keeps itself current, and stays out of the way
Velatir for Desktop is a small agent that runs in the background on each device. Once installed it needs nothing from your team, and everything it does is managed from Velatir.
## What it does
* **Captures AI usage.** It watches the AI apps your organisation uses, in the browser and in desktop and CLI apps, and turns each interaction into a trace your [agents](/agents/understanding-agents) review.
* **Inspects only AI apps.** Velatir looks only at traffic from the AI apps on its supported list. Everything else on the device is left completely untouched, so other software behaves exactly as before.
* **Updates itself.** The agent keeps itself current automatically, with no update service to manage.
## Managed capabilities
The installer is the same across an organisation's devices; Velatir applies the organisation's capability configuration after installation. The agent can manage device identity and health, browser coverage, local AI-app detection, directory identity, updates, and (where enabled) network capture independently. A missing or unavailable configuration fails safe: the device does not enable network capture or invent a capability setting.
Browser policy is ownership-aware. Organisations can have Velatir manage supported browser installation, write only the identity values while their own MDM manages installation, or leave browser policy entirely to their MDM. The agent removes only policy it owns.
## Network capture safety
Network capture is off by default and remains dormant until the organisation enables it and the device's safety checks pass. The agent performs the privileged machine changes; the host cannot bypass that boundary. If preflight or health checks fail, or a remote kill switch is engaged, capture is torn down and the device returns to the connectivity-first state.
The device reports its versions, capture state, health, update outcome, and directory identity in its heartbeat. This lets Velatir stage updates, halt an unhealthy rollout, and diagnose a device without requiring a reinstall.
## Inspecting encrypted traffic
AI traffic is encrypted, so to read it Velatir presents a certificate the device trusts. It generates a unique certificate authority per device, sets it up only when capture is enabled, and removes it when capture is turned off or the app is uninstalled. Nothing shared is distributed, and a device that never enables capture holds no certificate at all.
Organisations that prefer to use their own certificate authority can [bring their own](/desktop-app/bring-your-own-ca).
## On macOS
The first time it runs, macOS asks the user to approve Velatir's network extension once. On managed Macs you can pre-approve this so there is no prompt; see [Enterprise deployment](/desktop-app/enterprise-deployment).
## Next steps
What Velatir asks for on each platform, and why.
How Velatir works alongside corporate VPNs.
Install on Windows or macOS.
Diagnose capture, certificate, and update issues.
# Overview
Source: https://docs.velatir.com/desktop-app/overview
One installer to monitor AI use across your fleet, in the browser and in desktop and CLI apps
**Velatir for Desktop** is the simplest way to roll Velatir out to your organisation. One installer for Windows or macOS, set up with a single ingest key. It then runs quietly in the background, keeps itself up to date, and needs nothing from your end users.
## What it covers
Velatir for Desktop monitors how your organisation uses AI across managed devices, giving you one view in the dashboard. It covers:
* **AI in the browser:** ChatGPT, Claude, Gemini, and thousands of other web platforms.
* **AI in desktop and CLI apps:** the assistants your team uses outside the browser, listed below.
Every captured interaction becomes a trace your [agents](/agents/understanding-agents) review.
### Supported applications
| Application | Where it runs | Windows | macOS |
| ------------------------- | -------------------------------------------------------------------------- | :-----: | :---: |
| **GitHub Copilot** | VS Code, JetBrains Rider, IntelliJ IDEA, Visual Studio, Xcode, Neovim, CLI | ✓ | ✓ |
| **Microsoft Copilot** | Word, Excel, PowerPoint, Outlook, Teams | ✓ | ✓ |
| **Microsoft Copilot app** | Standalone desktop app | ✓ | ✓ |
| **Claude Code** | CLI and VS Code | ✓ | ✓ |
| **Claude Desktop** | Native desktop app | ✓ | ✓ |
| **Claude for Word** | Microsoft Word | ✓ | ✓ |
| **ChatGPT for Word** | Microsoft Word | ✓ | ✓ |
Only the AI apps in this list are inspected. Everything else on the device is left untouched. Need another app covered? Ask your account team.
## Supported platforms
| Platform | Status |
| ------------------------------------------------- | ----------- |
| Windows 10 / 11 (x64, arm64) | Available |
| macOS 13 Ventura and later (Intel, Apple Silicon) | Available |
| Linux | Coming soon |
## Get started
Install on a single device in a few minutes.
Roll out silently across your fleet with Intune, Jamf, or any MDM.
# Permissions
Source: https://docs.velatir.com/desktop-app/permissions
The operating system permissions Velatir for Desktop needs on Windows and macOS, and why
## Overview
Velatir for Desktop needs a small set of operating system permissions to capture and inspect AI traffic on a managed device. Everything is requested at install time, and the list is short on purpose: there is no microphone, camera, location, or full-disk access.
## Windows
The installer asks for administrator rights once. It uses them to set up traffic capture, install the certificate Velatir needs to inspect AI traffic, and register the background service. After that, the [CLI](/desktop-app/cli) asks for elevation only for commands that change capture or configuration.
Velatir then runs as a background service that starts automatically, so it keeps working across reboots without anyone needing to launch it. A tray icon shows when it is running.
| Prompt | When | What it grants |
| -------------------------- | ----------------------------------------------------------- | -------------------------------------- |
| User Account Control (UAC) | At install | Administrator rights for the installer |
| UAC for some CLI commands | Running `velatir start`, `stop`, `set-api-key`, and similar | Per-command elevation for changes |
## macOS
The installer asks for an administrator password once, the standard macOS installer flow. Velatir captures traffic through an approved macOS **system extension**. There is no kernel extension and no patching of system frameworks.
On first run, macOS asks the user to approve Velatir's network extension in **System Settings → General → Login Items & Extensions → Network Extensions**. Until it is approved, capture cannot start. On managed Macs you can pre-approve it so there is no prompt; see [Enterprise deployment](/desktop-app/enterprise-deployment). The extension grants no access to files, user data, or any other system resource.
Velatir trusts its per-device certificate in the macOS System keychain, so browsers and apps inspect correctly. Some runtimes keep their own trust store; see [Troubleshooting](/desktop-app/troubleshooting). To use your own certificate authority instead, see [Bring your own certificate](/desktop-app/bring-your-own-ca).
| Prompt | When | What it grants |
| ----------------------------------- | ----------------------------------------------------------- | ---------------------------------------------- |
| Administrator password | At install | Permission to run the installer |
| System extension approval | First run | Permission to load Velatir's network extension |
| Authorisation for some CLI commands | Running `velatir start`, `stop`, `set-api-key`, and similar | Per-command elevation for changes |
## Next steps
How Velatir works alongside corporate VPNs.
Silent install, bring-your-own CA, and MDM rollouts.
What Velatir stores and how it scrubs sensitive content.
Diagnose certificate and approval issues.
# Desktop rollout safety
Source: https://docs.velatir.com/desktop-app/rollout-safety
How Velatir for Desktop is introduced and updated safely across an organisation
Velatir for Desktop is designed for a single deployment per device. The installer installs the stable agent root and payload; capability configuration, detection rules, browser policy, and payload updates arrive through the managed update path rather than customer-specific installers.
## Safe defaults
Network capture is off by default. A configuration-fetch failure, unknown organisation, failed preflight, unhealthy capture state, or remote kill switch leaves the device in the connectivity-first state. The agent owns privileged network changes and independently re-checks the effective capability before starting capture.
The lower-risk capabilities are separate from network capture:
* device identity and heartbeat;
* local AI-application detection;
* directory identity enrichment;
* browser policy reconciliation;
* update and health reporting.
This allows an organisation to deploy the agent and establish device visibility without immediately changing its network path.
## Staged updates
Updates are resolved from the organisation's version pin, the current rollout ring, and the stable channel. Rollouts are staged and health-gated rather than sent to the entire fleet at once. The device retains the previous payload and applies updates through an atomic swap after capture has been safely torn down.
The heartbeat reports the agent version, payload version, active and target capture drivers, capture engagement, health, and last update outcome. These signals support rollout bake windows, automatic halt decisions, and investigation of unhealthy devices.
## Existing deployments
Existing deployments must be pre-seeded before a default-off payload is introduced. Their backend capability state must reproduce the behaviour they already rely on, and they must enter a late rollout ring rather than a canary ring. This avoids silently disabling active capture while preserving the safe default for new devices.
## What administrators need to provide
A rollout needs one organisation-scoped ingest key. Platform and architecture determine the installer artifact; capability behaviour is selected by the backend after installation. Customer-managed browser policy and advanced certificate or machine-identity arrangements remain explicit overrides rather than hidden installer variants.
# Troubleshooting
Source: https://docs.velatir.com/desktop-app/troubleshooting
Diagnose and resolve common issues with the Velatir desktop client: fleet rollout, interception, certificates, updates, and the CLI
## Overview
To diagnose most issues, run:
```bash theme={null}
velatir status
velatir logs --host -f
```
Then reproduce the issue in a supported AI application and watch the log.
If the client never arrived on the device in the first place, start with [Fleet and MDM](#fleet-and-mdm) instead.
## Fleet and MDM
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 no application bundle in `/Applications`. 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](/desktop-app/enterprise-deployment#deploy-with-your-mdm). 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.
The installer never ran, so there is nothing on the device to find. Check in this order:
```bash theme={null}
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:
```bash theme={null}
sudo installer -pkg Velatir-Bootstrap-macos-arm64.pkg -target /
velatir status
```
Check what actually reached the device:
```bash theme={null}
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.
Set the key directly to get the device working now, then correct the profile:
```bash theme={null}
sudo velatir set-api-key --key vltr_your_api_key_here
```
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:
```bash theme={null}
sudo velatir set-api-key --key vltr_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.
## Interception
Confirm in this order:
1. **Velatir is running.** `velatir status` should show capture active.
2. **Ingest key configured.** `velatir get-config` should show a masked ingest key. If empty, set it: `velatir set-api-key --key vltr_...`.
3. **The application is supported.** Velatir captures only supported applications. See [Overview](/desktop-app/overview#supported-applications).
4. **Certificate trust.** Some runtimes use their own trust store. See [Certificate not trusted by a specific runtime](#certificate-not-trusted-by-a-specific-runtime).
5. **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.
This is expected. Velatir only captures supported AI applications; everything else is passed through untouched.
To request coverage for an application, contact your account team with the application name, vendor, operating system, and the AI provider it talks to (for example, "Editor X on Windows talks to api.anthropic.com").
**Windows:** usually the install did not complete correctly. Reinstall the MSI with administrator elevation. If it persists, run `velatir logs -f` while attempting `velatir start` and capture the error.
**macOS:** usually the system extension has not been approved. Open **System Settings → General → Login Items & Extensions → Network Extensions** and confirm **Velatir** is enabled. See [Permissions](/desktop-app/permissions#macos).
## Certificates
Browsers and most native apps use the operating system trust store and pick up the Velatir CA automatically. A few runtimes use their own trust store and need explicit configuration.
**Node.js**
```bash theme={null}
export NODE_EXTRA_CA_CERTS=/path/to/velatir-ca.crt
```
On macOS the installer sets this automatically. Restart any Node.js process that was running before the install.
**Python (`requests`, `urllib`)**
```bash theme={null}
export SSL_CERT_FILE=/path/to/velatir-ca.crt
export REQUESTS_CA_BUNDLE=/path/to/velatir-ca.crt
```
**JVM**
Import the Velatir CA into the JVM truststore:
```bash theme={null}
keytool -importcert -trustcacerts \
-keystore "$JAVA_HOME/lib/security/cacerts" \
-storepass changeit \
-alias velatir \
-file /path/to/velatir-ca.crt
```
**curl**
`curl` follows the OS trust store on macOS and Windows. On Linux, point it explicitly:
```bash theme={null}
curl --cacert /path/to/velatir-ca.crt https://...
```
Some applications only trust one specific certificate and reject any other. There is no workaround; Velatir detects these connections and passes them through unmodified.
If a pinned application is critical to your compliance workflow, contact your account team about coverage options.
## Agent and Host
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](#fleet-and-mdm).
If it keeps disappearing, run `velatir logs -f` (it reconnects once the client comes up) and share the output with support.
Velatir restarts itself within 30 seconds if it stops unexpectedly. Frequent restarts usually mean a problem. Inspect the log:
```bash theme={null}
velatir logs --host
```
Common causes: an invalid ingest key, a bad bring-your-own CA password, or (rarely) a failed update. Reset to a known-good state by reapplying the ingest key:
```bash theme={null}
velatir set-api-key --key vltr_your_api_key_here
```
Velatir only runs one copy at a time, so an accidental second launch exits silently. This is expected. To restart it:
```bash theme={null}
velatir host restart
```
## Updates
Velatir checks for updates periodically. To force a check now:
```bash theme={null}
velatir update
velatir update --apply
```
If the version is still older than expected, or you use a tenant-specific update channel, contact support.
A failed update stays on the previous version. Inspect the log:
```bash theme={null}
velatir logs -f
```
A common cause is insufficient disk space. Free up space and retry with `velatir update --apply`.
## Networking
Velatir re-binds on its own when the network changes, so this usually resolves within seconds. If it does not:
```bash theme={null}
velatir restart
```
See [VPN compatibility](/desktop-app/vpn-compatibility).
On Windows, Velatir keeps known AI hosts on a connection it can observe; other traffic (including HTTP/3 to non-AI sites) is untouched, so this rarely causes visible issues. On macOS, QUIC is not captured at all.
## Getting Help
When you contact support, attach:
```bash theme={null}
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
Quick answers to common questions.
Full command surface for diagnosing and recovering.
What the app needs from the operating system, and why.
Detail on coexistence with corporate VPNs.
# Uninstall Cleanup
Source: https://docs.velatir.com/desktop-app/uninstall-cleanup
Remove every trace of Velatir for Desktop from a Windows device when a standard uninstall leaves something behind
A standard uninstall removes Velatir. This page is for when it does not — the device will not come off through your MDM, the uninstall was interrupted, or items remain once it has finished. The cleanup script below removes everything Velatir put on a Windows device, and is safe to run alongside or instead of `msiexec /x`.
Start with the standard route in [Download and install](/desktop-app/download-and-install#updates-and-uninstall). Come here if it does not finish the job.
A full run removes Velatir completely — including a version you may want to keep. If the device is already running a current version and you only want to clear out what an older one left behind, use [`-LegacyOnly`](#already-running-a-newer-version).
## When you need it
| Symptom | What is happening |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| The app is still listed after uninstalling | The uninstall was interrupted before it finished |
| Your MDM reports the uninstall as failed, or nothing changes | The MDM never ran the removal, so nothing was removed |
| The device lost internet after a forced removal | A network route survived the process that owned it |
| An older version leaves items behind | Older versions used a different capture method, with artefacts a standard uninstall does not clear |
## Get the script
## Run it on one device
Preview first — this changes nothing:
```powershell theme={null}
powershell -ExecutionPolicy Bypass -File .\Uninstall-VelatirDesktopApp.ps1 -DryRun
```
Then run it for real:
```powershell theme={null}
powershell -ExecutionPolicy Bypass -File .\Uninstall-VelatirDesktopApp.ps1
```
It asks for administrator rights if you start it without them. Every step is independent, so one failure never stops the rest, and you can run it again as many times as you need.
Restart the device afterwards to finish clearing a removed network adapter. Internet access returns without a restart — the script repairs routes first, before the slower work, so a device that lost connectivity is usable again immediately.
## Deploy it with Intune
Set the Velatir app assignment to **Uninstall**, or remove it. While it is still assigned as **Required**, Intune reinstalls the app behind the cleanup and the device looks unchanged.
Go to **Devices → Scripts and remediations**, add the script, and set it to run as **SYSTEM** in **64-bit** PowerShell. A remediation script needs no detection rule, so a detection rule that never matches cannot block the removal.
```powershell theme={null}
powershell -ExecutionPolicy Bypass -NoProfile -File .\Uninstall-VelatirDesktopApp.ps1 -NoSelfElevate
```
`0` means the device is clean. `2` means something remains — restart those devices and run it again. The device also writes a full transcript to `%TEMP%\Velatir-uninstall-.log`.
The same approach works for any MDM or RMM tool that can run PowerShell as SYSTEM.
Removing Velatir is not an upgrade path. If you want a device on a current version, uninstall and then install again — see [Download and install](/desktop-app/download-and-install).
## Already running a newer version
If a device was updated to a current version **before** you ran the cleanup, an older version's leftovers are stranded underneath a working install. Add `-LegacyOnly`:
```powershell theme={null}
powershell -ExecutionPolicy Bypass -File .\Uninstall-VelatirDesktopApp.ps1 -LegacyOnly
```
This removes only what a current version cannot own, and checks each item is genuinely orphaned before touching it. It never runs `msiexec`, and never removes the service, the program directories, the registry keys, or the certificate your current install is using.
## What it removes
* The `VelatirAgent` service, the logon task older versions used, and any running Velatir processes
* Network routes and the `Velatir` network adapter, plus the packet-capture driver older versions installed
* Velatir firewall rules
* Velatir certificates from the trusted root stores
* `C:\Program Files\Velatir`, `C:\ProgramData\Velatir`, every user's `%LOCALAPPDATA%\Velatir`, and the Start menu shortcut
* Velatir registry keys, its entry in the machine `PATH`, and the `NODE_EXTRA_CA_CERTS` environment variable it set
## What it leaves alone
The script only ever removes things it can confirm are Velatir's:
| Left in place | Why |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Other VPN adapters | It matches the adapter named `Velatir` only, so WireGuard, Tailscale and similar keep theirs. The shared `wintun` driver other products rely on stays installed. |
| A packet-capture driver another product installed | Several products ship the same driver. It is removed only when it points at a Velatir directory, and reported and left alone otherwise. |
| Your own certificate authority | If you [bring your own CA](/desktop-app/bring-your-own-ca), it is not touched. |
| Your own `NODE_EXTRA_CA_CERTS` | Cleared only when the value points at a Velatir path. |
| Your network configuration | No IP-stack reset. Only Velatir's own routes are deleted, so your real default route survives. |
## Confirm the device is clean
The script prints a verification report and exits `2` if anything remains. To check by hand:
```powershell theme={null}
# No Velatir certificate in the trusted root store - expect no results
Get-ChildItem Cert:\LocalMachine\Root, Cert:\CurrentUser\Root |
Where-Object Subject -like '*Velatir*'
# No service, no files - expect no results
Get-Service VelatirAgent -ErrorAction SilentlyContinue
Test-Path 'C:\Program Files\Velatir', 'C:\ProgramData\Velatir'
```
On macOS with Firefox, the Velatir browser extension may still be listed after uninstalling. It is inactive, and Firefox does not remove policy-installed extensions by itself. See [Download and install](/desktop-app/download-and-install#updates-and-uninstall) for how to remove it.
## Next steps
Install a current version on a cleaned device.
Roll out across your fleet with Intune, Jamf, or any MDM.
Resolve install and first-run issues.
Common questions about the desktop app.
# VPN Compatibility
Source: https://docs.velatir.com/desktop-app/vpn-compatibility
How Velatir for Desktop works alongside corporate VPNs
Velatir for Desktop is designed to coexist with corporate VPNs, including split-tunnel and full-tunnel setups and zero-trust agents.
## How it behaves
Velatir captures AI traffic however your VPN routes it, and everything else continues to use your VPN exactly as before.
| VPN configuration | Behaviour |
| ----------------- | --------------------------------------------------------------------------------------------- |
| No VPN | Velatir captures AI traffic. All other traffic is unaffected. |
| Split-tunnel | Velatir captures AI traffic. Traffic to corporate resources still goes through the VPN. |
| Full-tunnel | Velatir captures AI traffic and sends it on over the VPN. Corporate resources stay reachable. |
When the network changes (a VPN connects or disconnects, or the device roams between networks), Velatir adjusts on its own within seconds, so no restart is needed. If you ever need to force it, run `velatir restart` (administrator rights required on Windows).
## Zero-trust agents
Velatir works with userspace zero-trust agents that operate at the application layer. If another tool captures traffic at the same low level as Velatir, the two can conflict; contact support before deploying alongside one.
## Checking it
```bash theme={null}
velatir status
velatir logs --host -f
```
`status` confirms the agent is running. To watch live, run the logs command and trigger an AI interaction in a supported app.
## Next steps
Resolve capture and connectivity issues.
The `restart`, `status`, and `logs` commands in detail.
What Velatir asks for on each platform.
Roll out alongside corporate VPNs at scale.
# Insights Overview
Source: https://docs.velatir.com/insights/overview
See how your organisation uses AI, where activity concentrates, and what agents catch.
## What Are Insights?
Insights give you a clear picture of how your organisation uses AI. Instead of reading individual traces, you see the patterns: which services are used, how much is happening, and where your deployment has reached.
Use insights to spot trends, find gaps, and make governance decisions based on real activity.
## Two Views
A single view across your whole organisation, with headline numbers and breakdowns.
The same picture broken down per workspace, so you can compare teams and sort by what matters.
## What You See
| Metric | What it tells you |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **Services** | Which AI services are in use, and in what categories |
| **Users** | How many active users there are, as an aggregate count |
| **Sessions** | How much AI activity is happening over time |
| **Deployment** | How far the browser extension and desktop app have rolled out |
| **User concentration** | Whether AI use is spread across the organisation or concentrated in a small part of it |
## Focus the View
Narrow insights to the slice you care about.
* **Time range:** today, the last 7 days, 30 days, or year.
* **Origin:** all activity, web, or desktop.
* **Teams:** filter by department, office, or group when [Microsoft Entra](/platform/microsoft-entra) is connected.
Need a report to share? Use **Export** to produce a PDF of the current view for a meeting or a board pack.
## Using Insights Well
Spot unapproved services or unusual patterns before they become incidents.
Base your service policy and data categories on how your organisation actually uses AI.
Watch how usage grows and check that your governance keeps pace.
***
Browse the AI services Velatir can detect.
Break activity down by department, office, and group.
# Service Catalogue
Source: https://docs.velatir.com/insights/service-catalog
The inventory of AI services Velatir monitors across your organisation.
## What Is the Service Catalogue?
The service catalogue is Velatir's inventory of over 4,000 AI services it can detect and monitor. It gives you a full view of which AI services exist, which ones your organisation actually uses, and how they are categorised.
Use the catalogue to understand the AI landscape in your organisation. It answers the question: what AI services are my people using, and what do I need to know about them?
## How Services Are Detected
The browser extension identifies AI services used in the browser. This covers web tools, SaaS platforms, and browser-based interfaces.
The desktop app identifies AI services running as native applications or built into local workflows.
Together, these cover both web and desktop AI usage.
## Using the Catalogue
Open the catalogue and browse by category, or search for a specific service by name.
Select a service to see its category, how it is detected, its EU sovereignty status, and how much your organisation uses it.
Filter to the services your organisation uses and look for unapproved tools, unexpected categories, or heavy outliers.
Use what you learn to set your [Gatekeeper](/agents/gatekeeper) policy and discuss approved services with your teams.
## Categories
The catalogue groups services into categories, so you can quickly see what kinds of AI your organisation relies on, from language tools to image generation to code assistants. Filtering by category helps you answer targeted questions, such as which code assistants are in use.
## EU Sovereignty
For organisations with EU data residency requirements, the catalogue flags whether each service operates within EU infrastructure. This helps you identify services that may raise data sovereignty concerns and act on them.
***
See aggregated activity across your organisation.
Decide which services are allowed.
# Introduction to Velatir
Source: https://docs.velatir.com/introduction
Compliance monitoring for how your organisation uses AI, with agents and human oversight.
## What is Velatir?
Velatir is a compliance platform that monitors how your organisation uses AI. Every interaction is captured, assessed by agents, and logged for audit purposes. When an agent finds a compliance risk, it can block the interaction or escalate it for human review.
## The Problem
Teams already use AI tools across the organisation. Most companies have little visibility into what data is being shared, which tools are in use, and whether interactions meet regulatory requirements.
* **Unmonitored usage.** People adopt AI tools without anyone seeing what data is shared.
* **Regulatory exposure.** The EU AI Act and GDPR require demonstrable oversight of AI usage.
* **Scattered oversight.** No single system tracks AI interactions across platforms, teams, and tools.
* **Delayed response.** Issues are often discovered after the fact.
## How Velatir Helps
Velatir brings four capabilities together to close these gaps.
Every AI interaction across your organisation is captured as a trace and grouped into sessions for full context.
Two agents review every trace. Gatekeeper controls which services can be used, and Data Protector catches sensitive content before it leaves your environment.
When something needs a person, the trace is escalated to Slack, Microsoft Teams, or a phone so the right people can respond.
Every trace, assessment, and decision is recorded with full context for compliance reporting.
## How It Works
Velatir captures AI interactions on each device (in the browser and in desktop apps) as traces, grouped into sessions.
Your active agents review each trace and reach a verdict, applying the categories and instructions you have configured.
Based on each agent's role, the trace is allowed, flagged, blocked, or escalated for approval.
Escalations are sent to your connected channels so the right people know about them.
The original trace, every assessment, and the outcome are recorded. Your audit trail is always complete.
## What You Get
See every AI interaction happening across your organisation in one place.
Agents review every trace against your service rules and data protection categories automatically.
Agents handle the routine work, so your team only reviews interactions that genuinely need a person.
Every interaction, assessment, and decision is logged with full context. You are always ready for an audit.
## Who Uses Velatir?
Velatir is built for organisations that want to adopt AI responsibly while keeping compliance and oversight in place.
* **IT and operations leaders.** Gain visibility into AI usage and apply governance without blocking productivity.
* **Compliance and legal teams.** Demonstrate regulatory compliance with complete audit trails and documented human oversight.
* **Security teams.** Watch for data leakage, unapproved tools, and sensitive information exposure in AI interactions.
## EU-Based and Secure
Velatir is built and hosted entirely within the EU. Your data stays in EU jurisdictions, and the platform is designed for GDPR compliance from day one.
***
Set up your organisation and start monitoring.
Understand how the platform fits together.
# Microsoft Entra
Source: https://docs.velatir.com/platform/microsoft-entra
Generate workspaces from your directory and organise activity by team.
## Why Connect Entra?
Connecting Microsoft Entra lets Velatir mirror how your organisation is actually structured. Instead of building and maintaining workspaces by hand, Velatir generates them from your directory and keeps them in step as people join, move, and change teams.
The same directory structure also organises activity by team, which powers the department and group breakdowns in [Insights](/insights/overview).
Connecting Entra is optional. You can always create and manage workspaces manually instead. See [Organisations & workspaces](/platform/organizations-and-workspaces).
## Generate Workspaces From Your Directory
When you set up your organisation, choose **Generate workspaces with Microsoft Entra** and pick which directory properties define your structure.
Pick the Entra user property that defines your top-level workspaces, for example **Department**. Velatir creates one workspace per value.
Add a second property, such as **Office** or **Group**, to nest workspaces beneath the first. You can nest up to two levels.
Everyone is assigned to the right workspace based on their directory details, and moved automatically when those details change.
## Properties You Can Use
| Property | Typical use |
| -------------- | --------------------------------------------------------- |
| **Department** | Top-level workspaces such as Engineering, Sales, or Legal |
| **Office** | Nested workspaces by location |
| **Group** | Nested workspaces by team or function |
## Activity by Team in Insights
Once Entra is connected, activity is organised by your directory structure: department, office, and group. You can filter and break usage down by these across the platform, so you see where AI is being adopted without singling out individuals.
Activity is grouped by department, office, and group, so the picture always matches how your organisation is set up.
Insights break usage down by department, office, and group, and show where adoption concentrates.
## Mapping Device Activity to Teams
So activity captured on a device lands in the right workspace, Velatir matches it to your directory structure using the organisational context the desktop client attaches to each trace.
***
How your account is structured.
See activity broken down by department, office, and group.
# Organisations & Workspaces
Source: https://docs.velatir.com/platform/organizations-and-workspaces
How Velatir structures your account into an organisation and workspaces.
## What Is an Organisation?
An organisation is your company account in Velatir. It holds your members, settings, agent defaults, and subscription in one place. Every customer starts with one organisation that represents their business.
Your organisation stores company-level settings such as your name, industry, country, and data privacy preferences. It also controls who has access and what they can do.
## What Is a Workspace?
A workspace is a space within your organisation for a specific team, department, or project. Workspaces keep activity clearly separated, and each one has its own traces and agent behaviour.
Workspaces can **nest**, so a top-level workspace such as Engineering can contain Platform and Mobile beneath it. This mirrors how your organisation is actually structured.
## How They Relate
Your company account. Holds all members, workspaces, and your subscription.
Spaces within your organisation, which can nest. Each has its own activity and agent behaviour.
You invite members to your organisation, then assign them to workspaces with a role for each.
## Creating Workspaces
When you set up your organisation, you choose how workspaces are created. You can change your structure later either way.
Create and name workspaces yourself. People are added to, and moved between, workspaces by hand. This suits small and medium organisations where people rarely move between teams.
Workspaces are generated from your directory, and people are assigned and moved automatically as their details change. This suits medium and large organisations where people move between departments and teams. See [Microsoft Entra](/platform/microsoft-entra).
## When to Use Multiple Workspaces
| Scenario | Example |
| ------------------------- | -------------------------------------------------------------- |
| **Separate teams** | Engineering, Marketing, and Legal each get their own workspace |
| **Nested structure** | A Sales workspace with regional workspaces beneath it |
| **Distinct projects** | One workspace per product line or client engagement |
| **Regulatory boundaries** | Workspaces for different jurisdictions or compliance regimes |
A single workspace works fine if your whole organisation shares one context. Add more whenever you need clear boundaries between groups of activity.
## Agent Configuration Across Workspaces
Agents are configured at the organisation level and apply everywhere by default. Any workspace can override that default with its own settings, or turn an agent off entirely. This gives you central control with room to tailor behaviour for specific teams. See [Configuring agents](/agents/configuring-agents).
## Organisation Settings
Update your organisation name, industry, and country. These details help Velatir tailor its insights to your context.
Invite members and manage their organisation roles. From here you also assign members to workspaces.
Choose whether Velatir saves or scrubs session content, and set your retention period. See [Data privacy](/security/data-privacy).
Connect Slack, Microsoft Teams, or a phone so escalations reach the right people.
View your current plan and invoices.
***
What each role can do at the organisation and workspace level.
Generate workspaces from your directory.
# Roles & Permissions
Source: https://docs.velatir.com/platform/roles-and-permissions
Organisation and workspace roles in Velatir and what each one can do
## What Are Roles?
Roles control what members can see and do within your Velatir account. Velatir uses two layers of roles. Organisation roles govern your entire account. Workspace roles control access within individual workspaces.
Every member receives an organisation role when invited. They then receive a workspace role for each workspace they are assigned to.
## Organisation Roles
Organisation roles determine what a member can do across your entire Velatir account.
| Role | Description | Key Permissions |
| ----------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Administrator** | Full control over the organisation | Manage settings, billing, members, and all workspaces. Create and delete workspaces. Invite and remove members. |
| **Reader** | View-only access to the organisation | View organisation settings and member lists. Cannot make changes or manage workspaces. |
Administrators handle day-to-day account management. Readers are suited for stakeholders who need visibility without the ability to make changes.
## Workspace Roles
Workspace roles determine what a member can do within a specific workspace. A member can hold different roles in different workspaces.
| Role | Description | Key Permissions |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| **Admin** | Full control over the workspace | Manage workspace settings, API keys, agents, and members. Full access to traces. |
| **Editor** | Manage traces | View and manage traces and agent configuration. Cannot change workspace settings or API keys. |
| **Reader** | View-only access to the workspace | View traces and agent activity. Cannot take any actions or make changes. |
## Choosing the Right Roles
Assign the Editor role so they can review traces and oversee agent activity across the workspace. If they only need to observe, Reader works.
Workspace Admin gives them full control to configure agents, manage API keys, and oversee their team's workspace.
Organisation Reader plus workspace Reader gives them visibility across the board without any risk of accidental changes.
## Inviting Members
Navigate to your organisation settings and select the Members section.
Enter the new member's email address and select their organisation role. They receive an email invitation to join.
Once they accept the invitation, assign them to one or more workspaces and choose a workspace role for each.
You can update roles at any time. Removing a member from a workspace revokes their access immediately.
***
Learn how organisations and workspaces are structured
Understand how Velatir handles data privacy and access control
# AI usage data specification
Source: https://docs.velatir.com/providers/ai-data-specification
For software providers integrating their AI features with Velatir.
Velatir gives organisations a single view of how AI is used across their business: oversight, compliance, and insight. To include your product in that view, Velatir connects to your system and retrieves a defined set of data describing how their people use its AI features.
This specification defines the data Velatir consumes and the shape it expects. The transport is your choice; the data model is what is normative.
Access is strictly read-only. Velatir retrieves data on a schedule and never sits in the path of a live request, so an integration cannot affect your users' experience.
## Resources
Velatir consumes four independent resource types. Implement those your system supports; apart from identifiers and timestamps, all fields are optional.
### 1. Conversations
One record per AI interaction: a conversation, or a single request and response exchange for stateless systems. This is the content Velatir's compliance agents review.
Stable, unique identifier for the interaction.
Thread identifier, where the interaction is part of a multi-turn conversation.
When the interaction began. RFC 3339, UTC.
When the record was last modified.
Present when the interaction has been deleted.
The person who ran the interaction.
The custom assistant used, if any. See [Assistants](#3-assistants).
Model used, for example `gpt-4o`.
Underlying LLM vendor, for example `openai`.
Sampling configuration: `temperature`, `topP`, `maxTokens`, and similar.
The system prompt in effect. Provide `systemPromptHash` instead where the text cannot be shared.
The turns of the interaction.
`user`, `assistant`, `system`, or `tool`.
Tools or skills invoked during the interaction.
Files exchanged during the interaction.
`uploaded` or `generated`.
Token counts and cost: `inputTokens`, `outputTokens`, `totalTokens`, `cost`.
Outcome of the interaction.
Any additional provider-specific fields, preserved as received.
### 2. Usage and cost
Aggregated, time-bucketed usage, for adoption and cost reporting.
Start of the bucket.
End of the bucket.
`hour` or `day`.
The grouping keys present in the bucket, any subset of the following.
The measured values for the bucket.
### 3. Assistants
Where your product allows customers to configure their own assistants, agents, or custom GPTs, one record per assistant describing its configuration.
For example `active` or `archived`.
The user who owns the assistant.
`private`, `team`, `organisation`, or `public`.
Default model.
Default sampling configuration.
The assistant's instructions. Provide `instructionsHash` instead where the text cannot be shared.
Tools or skills installed on the assistant.
`builtin`, `mcp`, `plugin`, or `function`.
Integrations and data sources connected to the assistant.
Attached knowledge or reference files.
Rollup: `conversationCount`, `userCount`, `lastUsedAt`.
### 4. Events
One record per notable action, forming an audit trail. Your native event type is preserved verbatim; the normalised fields are best-effort.
Your native event type.
Who performed the action.
`user`, `apiKey`, `serviceAccount`, or `system`.
`Authentication`, `Access`, `Configuration`, `DataMovement`, `ResourceLifecycle`, `Integration`, `Policy`, or `Other`.
`Created`, `Updated`, `Deleted`, `Enabled`, `Disabled`, `Exported`, `Shared`, and similar.
What the action affected.
For example an assistant, a skill, or a file.
The raw event body, preserved as received.
## Access and synchronisation
**Transport.** A read-only REST/JSON API is recommended and the simplest to integrate. An MCP server, a scheduled export, or webhooks are equally acceptable; the resource shapes above are what is normative.
**Authentication.** A single credential (bearer token or API key) per customer, scoped to that customer's data only. Per-resource scopes, for example `read:usage` or `read:conversations`, allow a customer to share usage metrics without exposing conversation content.
**Synchronisation.** Velatir retrieves data by polling on a schedule. The following are recommended rather than required; where they are absent, Velatir performs a full re-pull.
* **Stable identifiers.** A stable `id` on every record allows Velatir to update records in place rather than duplicate them on re-sync.
* **Timestamps.** RFC 3339, UTC. `updatedAt` and `occurredAt` allow Velatir to request only records that changed since the previous poll.
* **Pagination.** Lists that return `{ data[], hasMore, nextCursor }` with an opaque, retry-safe cursor allow Velatir to page through large histories reliably.
* **Incremental retrieval.** Filtering lists by `updatedSince` (conversations, assistants) and `occurredAfter` (events) avoids re-reading the full history on each poll.
* **Forward compatibility.** Fields and enum values may be added at any time. Velatir ignores unknown fields and never discards an unrecognised event `type`.
## Reference API
A minimal REST implementation consists of the following read-only endpoints:
```
GET /usage ?startAt&endAt&granularity&groupBy
GET /assistants ?updatedSince&cursor
GET /assistants/{id}
GET /conversations ?updatedSince&startedAfter&cursor
GET /conversations/{id}
GET /events ?occurredAfter&category&cursor
```
An example conversation record:
```json theme={null}
{
"id": "conv_8f21a0",
"conversationId": "thread_5521",
"startedAt": "2026-07-03T09:15:00Z",
"updatedAt": "2026-07-03T09:16:12Z",
"user": { "id": "u_204", "email": "user@company.com", "department": "Operations" },
"assistant": { "id": "asst_44", "name": "Support Assistant" },
"model": "gpt-4o",
"modelProvider": "openai",
"parameters": { "temperature": 0.4, "maxTokens": 1024 },
"systemPrompt": "You are a helpful assistant that ...",
"messages": [
{ "id": "m1", "role": "user", "content": "How do I process this request?", "createdAt": "2026-07-03T09:15:00Z" },
{ "id": "m2", "role": "assistant", "content": "First, you ...", "createdAt": "2026-07-03T09:15:04Z" }
],
"tools": [{ "id": "search", "name": "Knowledge search", "type": "builtin" }],
"usage": { "inputTokens": 320, "outputTokens": 210, "totalTokens": 530 }
}
```
# Quickstart
Source: https://docs.velatir.com/quickstart
Set up Velatir and start monitoring AI usage across your organisation.
This guide takes you from a new account to your first assessments. It should take about fifteen minutes.
## Before You Start
You need an organisation in Velatir and administrator access to it. If you are signing up for the first time, the onboarding wizard walks you through creating your organisation and your first workspaces.
When you create your organisation you can name workspaces yourself, or generate them automatically from your directory with Microsoft Entra. See [Microsoft Entra](/platform/microsoft-entra) to decide which fits your organisation.
## Set Up Monitoring
Open **Setup** in the dashboard. Most teams install **[Velatir for Desktop](/desktop-app/overview)**, one installer that covers AI use in the browser and in desktop apps. If you only need browser coverage, deploy the [browser extension](/setup/browser-extension) on its own.
On the Setup page, generate an API key. Copy it straight away, as it is shown only once. You can manage keys later under **Settings → API keys**.
Roll **Velatir for Desktop** out to your fleet with your ingest key. [Enterprise deployment](/desktop-app/enterprise-deployment) covers silent installation via Microsoft Intune, Jamf Pro, and other MDM platforms across Windows and macOS.
As people use AI, sessions and traces appear under **Sessions**, and agent verdicts appear under **Agents → Assessments**.
Open **Agents** to set how each one behaves. Start in Observer to learn your usage, then move to Enforcer where it matters. See [Configuring agents](/agents/configuring-agents).
## Recommended First Week
Keep both agents in Observer for the first week or two. You build a clear picture of what people use and what would be flagged, with no disruption.
Check **Agents → Assessments** to see what each agent caught. This tells you which services to allow or block and which data categories matter most.
Use [Gatekeeper](/agents/gatekeeper) to decide which AI services are allowed, and [Data Protector](/agents/data-protector) to decide which sensitive content to catch.
Add a channel under **Settings → Channels** so escalations reach the right people in Slack, Microsoft Teams, or by phone.
***
Understand organisations, agents, traces, and instructions.
Roll agents out from Observer to Enforcer.
# Data Privacy
Source: https://docs.velatir.com/security/data-privacy
How Velatir protects your data by default, with scrubbing, audit logs, and access controls.
## Privacy by Default
Velatir is built so that privacy is the starting point, not an afterthought. Session content is scrubbed unless you choose to keep it, every action is recorded in an audit trail, and you control who can access your account, including Velatir's own team.
## Session Content
By default, Velatir does not store the content of prompts and responses. It keeps the context it needs to monitor and report, such as which service was used and what an agent decided, without retaining the raw content people typed.
Out of the box, session content is removed before it is stored. You get full governance and compliance without holding raw user data.
If your compliance needs call for access to session content, you can turn on **Save session data** at the organisation level and set a **retention period** after which it is deleted automatically.
See [Data storage & encryption](/security/data-storage-and-encryption) for what is stored and how it is protected when you keep it.
## Configure It
Go to **Settings → General** and find the data privacy section.
Keep content scrubbed, the recommended default, or turn on Save session data if you need it.
If you keep session content, choose how long to retain it before it is deleted automatically.
## Audit Logs
Velatir keeps a complete record of what happens in your account. Every change, who made it, and when, is captured.
| Event | What is captured |
| ------------------------ | ----------------------------------------------------- |
| **Member actions** | Invitations, role changes, removals |
| **Settings changes** | Organisation and workspace configuration updates |
| **Escalation decisions** | Who responded to an escalation, and what they decided |
| **Agent changes** | Updates to agent configuration and instructions |
| **Access events** | Sign-in activity and permission changes |
Audit logs are immutable. They cannot be edited or deleted, which keeps the record trustworthy for reviews and audits.
## Support Access
Velatir's team has no access to your account by default. No one at Velatir can view your data, traces, or settings unless you grant access, and revoking it takes effect immediately.
## EU-Based Infrastructure
Velatir runs entirely on EU-based infrastructure. Your data stays within the European Union, which supports data residency and sovereignty requirements and aligns with GDPR. There are no data transfers to non-EU jurisdictions.
***
What is stored, and how it is protected.
Control who can see and change what.
Strip sensitive content from pasted text, on the device, before it is sent.
# Data Storage & Encryption
Source: https://docs.velatir.com/security/data-storage-and-encryption
What Velatir stores, how it is encrypted, and how your data stays separated.
## What Velatir Stores
For every trace, Velatir keeps the context it needs to monitor AI usage and produce an audit trail. The content of prompts and responses is treated separately, and is not stored unless you turn on Save session data.
| Always kept | Kept only if you opt in |
| ------------------------------------------------- | ---------------------------------------- |
| Which service was used and the trace direction | The content of prompts and responses |
| The agent assessments and outcomes | Function arguments and detailed metadata |
| Timestamps and the workspace the trace belongs to | |
See [Data privacy](/security/data-privacy) for how to choose your default and set a retention period.
## Encryption and Your Keys
When you keep session content, it is protected with strong, industry-standard encryption, and your organisation holds the keys.
Create encryption keys for your organisation in Settings. Content is encrypted to your key.
The private key needed to read content stays on your side. Velatir cannot read stored content without it.
This means even Velatir cannot read your session content. Only people in your organisation, holding the private key, can.
## Tenant Isolation
Every organisation's data is separated at the data layer. Your traces, sessions, and settings are scoped to your organisation, and there is no path for one organisation to reach another's data.
## Retention
If you keep session content, you choose how long to retain it. When the retention period passes, content is deleted automatically. This keeps you holding only what you need, for only as long as you need it.
## Data Exports
You can request an export of your data under **Settings → Data exports**. This supports your own record-keeping and helps you respond to data subject requests under GDPR.
***
Scrubbing, audit logs, and access controls.
How your account is structured.
# Browser Extension
Source: https://docs.velatir.com/setup/browser-extension
Monitor AI use in the browser with the Velatir browser extension
The browser extension monitors prompts and responses across 4,000+ AI platforms and sends them to your agents for assessment.
Most teams get the extension automatically with **[Velatir for Desktop](/desktop-app/overview)**: one installer that sets it up for you and also covers desktop apps. Use this section only to deploy the extension on its own, for browser-only coverage or when you push extensions through your own Group Policy or MDM.
## Install
Chrome, Brave, Arc, and Chromium browsers
Microsoft Edge
Mozilla Firefox
## Set up a single browser
1. Click the Velatir extension icon, then the settings gear.
2. Enter your **ingest key** from the [Velatir dashboard](https://app.velatir.com). It maps this machine's traces to your organisation.
3. Click **Save Settings**.
## Roll out to your organisation
To deploy across a fleet with the ingest key pre-configured, see the [Enterprise Deployment Guide](/setup/browser-extension-managed).
Deploy the extension with managed configuration across your fleet.
# Browser Extension - macOS (Jamf / MDM)
Source: https://docs.velatir.com/setup/browser-extension-macos
Deploy the Velatir browser extension to macOS with a configuration profile via Jamf Pro or any MDM
Deploy the extension to managed Macs with a single `.mobileconfig` profile. It handles force-install and managed storage for Chrome, Firefox, Vivaldi, and Brave.
## Generate your profile
Enter your ingest key (from the Velatir dashboard, under your organisation's settings). The same key is used for every browser. The profile is built locally in your browser, ready to upload to your MDM.
## Upload to your MDM
1. In Jamf Pro, go to **Computers** > **Configuration Profiles** > **Upload**.
2. Upload the generated `.mobileconfig` file.
3. Scope it to your target computers and save.
Any MDM that supports `.mobileconfig` files (Intune, Kandji, Mosyle, and others) follows the same upload-and-scope flow.
The Firefox payload sets `EnterprisePoliciesEnabled` to `true`. Without it, Firefox ignores all enterprise policy on macOS.
Edge and ChatGPT Atlas are not in this profile: managed configuration is not reliably delivered to their extensions on macOS, so the profile cannot pass them the ingest key. To use the extension there, install it from the browser's extension store and enter your ingest key from the popup.
## Inspect the profile
The profile is plain XML; the generator only substitutes your ingest key into the `apiToken` fields. To review it before deploying, click **Copy profile XML** above, or expand the reference template below (with a placeholder for your key).
```xml expandable velatir-browser-extension.mobileconfig theme={null}
PayloadContent
PayloadType
com.google.Chrome
PayloadIdentifier
com.velatir.chrome.forcelist
PayloadUUID
5ECD8344-941A-45C0-BE37-7E13BCBBBBBE
PayloadVersion
1
ExtensionInstallForcelist
bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx
PayloadType
com.google.Chrome.extensions.bbiokppljpbjgiogcoggjnfffbeiihja
PayloadIdentifier
com.velatir.chrome.extension.config
PayloadUUID
5102578B-1554-4556-B895-591A7621A7F8
PayloadVersion
1
apiToken
vltr_yourIngestKeyHere
PayloadType
org.mozilla.firefox
PayloadIdentifier
com.velatir.firefox.config
PayloadUUID
8B2A4F6E-3D5C-4A1B-9E7F-2C6D8A0B4E1C
PayloadVersion
1
EnterprisePoliciesEnabled
ExtensionSettings
velatir@velatir.com
installation_mode
force_installed
install_url
https://addons.mozilla.org/firefox/downloads/latest/velatir/latest.xpi
3rdparty
Extensions
velatir@velatir.com
apiToken
vltr_yourIngestKeyHere
PayloadType
com.vivaldi.Vivaldi
PayloadIdentifier
com.velatir.vivaldi.forcelist
PayloadUUID
A1F0C4D2-9B3E-4C7A-8F5D-2E8B1C4A6D90
PayloadVersion
1
ExtensionInstallForcelist
bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx
PayloadType
com.vivaldi.Vivaldi.extensions.bbiokppljpbjgiogcoggjnfffbeiihja
PayloadIdentifier
com.velatir.vivaldi.extension.config
PayloadUUID
B2E1D5C3-AC4F-4D8B-9061-3F9C2D5B7E01
PayloadVersion
1
apiToken
vltr_yourIngestKeyHere
PayloadType
com.brave.Browser
PayloadIdentifier
com.velatir.brave.forcelist
PayloadUUID
C3D2E6F4-BD5A-4E9C-A172-4A0D3E6C8F12
PayloadVersion
1
ExtensionInstallForcelist
bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx
PayloadType
com.brave.Browser.extensions.bbiokppljpbjgiogcoggjnfffbeiihja
PayloadIdentifier
com.velatir.brave.extension.config
PayloadUUID
D4E3F7A5-CE6B-4F0D-B283-5B1E4F7D9023
PayloadVersion
1
apiToken
vltr_yourIngestKeyHere
PayloadDisplayName
Velatir Browser Extension
PayloadIdentifier
com.velatir.browser.profile
PayloadType
Configuration
PayloadUUID
D582F777-FEBE-4B67-A3DC-35FD07F37E03
PayloadVersion
1
```
***
Confirm the profile applied and the extension is installed
Browser support, managed config, and other platforms
# Browser Extension - Managed Deployment
Source: https://docs.velatir.com/setup/browser-extension-managed
Browser support, managed configuration, and deployment methods for rolling the Velatir browser extension out across your organisation
Deploy the extension to managed devices with the ingest key pre-configured. Pick a method below; the browser support and configuration reference follow.
Deploying **[Velatir for Desktop](/desktop-app/overview)**? It handles all of this for you. Use this guide only if you manage browser extensions through your own Group Policy or MDM.
## Deployment methods
Force-install via GPO, PowerShell, manual registry, or the Intune Settings Catalog. Chrome, Edge, Firefox, Vivaldi, and Brave.
A single .mobileconfig profile for Chrome, Firefox, Vivaldi, and Brave.
Island, Prisma Access, Surf, and browsers with no policy surface.
## Extension IDs
| Browser | Extension ID | Store |
| --------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Chrome | `bbiokppljpbjgiogcoggjnfffbeiihja` | [Chrome Web Store](https://chromewebstore.google.com/detail/velatir/bbiokppljpbjgiogcoggjnfffbeiihja) |
| Edge | `phgnjcoglpdamjjmidheehacjbkgkooc` | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/velatir/phgnjcoglpdamjjmidheehacjbkgkooc) |
| Firefox | `velatir@velatir.com` | [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/velatir/) |
| Vivaldi | `bbiokppljpbjgiogcoggjnfffbeiihja` | Chrome Web Store (same as Chrome) |
| Brave | `bbiokppljpbjgiogcoggjnfffbeiihja` | Chrome Web Store (same as Chrome) |
| ChatGPT Atlas (macOS) | `bbiokppljpbjgiogcoggjnfffbeiihja` | Chrome Web Store (same as Chrome) |
Vivaldi, Brave, and Atlas install the Chrome Web Store build (same extension ID, same managed-storage schema), so no separate listing is needed.
## Supported browsers
The [deployment methods](#deployment-methods) cover every browser with an enterprise policy surface.
| Browser | Deployment | Policy location |
| --------------------------------- | ------------------------- | ------------------------------------------------------------------ |
| Chrome | MSI / GPO / mobileconfig | `HKLM\SOFTWARE\Policies\Google\Chrome` / `com.google.Chrome` |
| Edge | MSI / GPO / mobileconfig | `HKLM\SOFTWARE\Policies\Microsoft\Edge` / `com.microsoft.Edge` |
| Firefox | MSI / GPO / mobileconfig | `HKLM\SOFTWARE\Policies\Mozilla\Firefox` / `org.mozilla.firefox` |
| Vivaldi | MSI / GPO / mobileconfig | `HKLM\SOFTWARE\Policies\Vivaldi` / `com.vivaldi.Vivaldi` |
| Brave | MSI / GPO / mobileconfig | `HKLM\SOFTWARE\Policies\BraveSoftware\Brave` / `com.brave.Browser` |
| ChatGPT Atlas | mobileconfig (macOS only) | `com.openai.atlas.web` |
| Island, Prisma Access, Surf | Vendor console | [Vendor-managed browsers](#vendor-managed-browsers) |
| Comet, Arc, Dia, Opera / Opera GX | Manual install | [No policy surface](#browsers-without-a-policy-surface) |
## Managed configuration
The extension reads its configuration from managed storage:
| Property | Type | Description |
| ---------- | ------ | -------------------------------------------------------------------------------------------------- |
| `apiToken` | string | Your organisation's ingest key (e.g. `vltr_...`). Maps each machine's traces to your organisation. |
It fetches your organisation's display name from the platform, so that is not configured through managed storage.
## Vendor-managed browsers
Island, Prisma Access Browser (formerly Talon), and Surf Security run their own management plane and do not honour host-OS Chromium policy keys or preference plists. Force-install and pre-configure the extension from each vendor's admin console using these values:
| Field | Value |
| -------------------- | ------------------------------------------------- |
| Extension ID | `bbiokppljpbjgiogcoggjnfffbeiihja` |
| Update URL | `https://clients2.google.com/service/update2/crx` |
| Managed-storage JSON | `{"apiToken":"vltr_yourIngestKeyHere"}` |
| Browser | Where | Steps |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Island | Island admin console | **Device Management > Extensions > Extension Policy**: add the ID, set **Force-installed**, paste the JSON, scope to your groups. |
| Prisma Access | [Strata Cloud Manager](https://docs.paloaltonetworks.com/prisma-access-browser/administration/manage-prisma-access-browser-extensions) | In the browser policy profile under **Manage Extensions**, force-install the ID from the update URL and paste the JSON. Force-install must go through Strata Cloud Manager, not the registry. |
| Surf | Surf admin console | In extension management, add the ID as force-installed and paste the JSON. |
## Browsers without a policy surface
Comet, Arc, Dia, and Opera / Opera GX publish no framework to force-install an extension. Users install it manually:
1. Open the [Chrome Web Store listing](https://chromewebstore.google.com/detail/velatir/bbiokppljpbjgiogcoggjnfffbeiihja).
2. Click **Add to browser** (on Opera, via Opera's "Install Chrome Extensions" add-on).
3. Open the Velatir popup and enter the ingest key.
We will add these to the MSI / mobileconfig if and when the vendors publish a policy reference.
## Verify
After the profile or policy applies:
* Open the browser's policy page and confirm the Velatir extension ID is force-installed with your `apiToken`: `chrome://policy`, `edge://policy`, `vivaldi://policy`, `brave://policy`, or `about:policies` (Firefox shows `velatir@velatir.com` set to `force_installed`).
* Open the extensions page and confirm Velatir is present: `chrome://extensions`, `edge://extensions`, `about:addons` (Firefox: "Installed by enterprise policy"), `vivaldi://extensions`, `brave://extensions`. For Atlas, use the extensions panel in the Atlas menu.
* On Windows, trigger an Intune sync first, then **Reload policies** on the policy page.
* On macOS, confirm the managed-preference plist exists, e.g. `ls /Library/Managed\ Preferences/com.google.Chrome.plist`.
## Troubleshoot
* **Extension not installing**: confirm the browser was installed before the policy applied, and check the policy page for errors. Windows: confirm the device synced with Intune (**Devices > Monitor > Device configuration status**). macOS: confirm the profile is installed under **System Settings > Privacy & Security > Profiles**. Firefox (macOS): set `EnterprisePoliciesEnabled` to `true`, or Firefox ignores all policies.
* **Configuration not appearing**: restart the browser after policy changes. Windows: run scripts in 64-bit PowerShell with administrator / SYSTEM rights, or registry writes land under `WOW6432Node`. macOS: match the preference domain exactly. Firefox (Windows) with `policies.json`: confirm the file is at `C:\Program Files\Mozilla Firefox\distribution\policies.json`, which Firefox updates can remove.
* **Policy conflicts (Windows)**: if multiple Intune profiles set `ExtensionInstallForcelist`, use the [PowerShell script](/setup/browser-extension-windows-advanced) instead of the Settings Catalog. It writes to a high value name (`1000`) that does not collide with MDM-managed entries.
***
Features and manual installation
Set up your account and get your ingest key
# Browser Extension - Windows (Group Policy / Registry)
Source: https://docs.velatir.com/setup/browser-extension-windows-advanced
Force-install the Velatir browser extension on Windows via Group Policy, PowerShell, manual registry, or the Intune Settings Catalog
Force-install the extension on Windows by pushing browser policy yourself: through Group Policy, a PowerShell script, a `policies.json` file, or the Intune Settings Catalog. These cover Chrome, Edge, Firefox, Vivaldi, and Brave, and all write to the machine hive (`HKLM\Software\Policies\…`).
## PowerShell script
One script covers all five browsers. Edit `$IngestKey` at the top, then run it as Administrator or SYSTEM in 64-bit PowerShell. The browsers read the key from the registry value `apiToken`.
**Configuration script** (`Configure-Velatir.ps1`):
```powershell expandable theme={null}
# Configuration - UPDATE THIS VALUE
$IngestKey = "your-ingest-key-here"
# Extension IDs
# Vivaldi and Brave install the Chrome Web Store build of the extension and
# therefore share Chrome's extension ID.
$ChromeId = "bbiokppljpbjgiogcoggjnfffbeiihja"
$EdgeId = "phgnjcoglpdamjjmidheehacjbkgkooc"
$FirefoxId = "velatir@velatir.com"
$VivaldiId = $ChromeId
$BraveId = $ChromeId
# Machine ID: Windows computer name. Matches the MSI's [ComputerName] behaviour.
$MachineId = $env:COMPUTERNAME
function Set-ManagedPolicy($Path, $Key, $Id) {
if (-not (Test-Path $Path)) {
New-Item -Path $Path -Force | Out-Null
}
Set-ItemProperty -Path $Path -Name "apiToken" -Value $Key -Type String
Set-ItemProperty -Path $Path -Name "machineId" -Value $Id -Type String
}
# Chrome
$ChromeForcelist = "HKLM:\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist"
if (-not (Test-Path $ChromeForcelist)) {
New-Item -Path $ChromeForcelist -Force | Out-Null
}
# Use name "1000" to avoid colliding with MDM-managed entries (which start at 1)
Set-ItemProperty -Path $ChromeForcelist -Name "1000" -Value "$ChromeId;https://clients2.google.com/service/update2/crx" -Type String
Set-ManagedPolicy "HKLM:\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\$ChromeId\policy" $IngestKey $MachineId
# Edge
$EdgeForcelist = "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist"
if (-not (Test-Path $EdgeForcelist)) {
New-Item -Path $EdgeForcelist -Force | Out-Null
}
Set-ItemProperty -Path $EdgeForcelist -Name "1000" -Value "$EdgeId;https://edge.microsoft.com/extensionwebstorebase/v1/crx" -Type String
Set-ManagedPolicy "HKLM:\SOFTWARE\Policies\Microsoft\Edge\3rdparty\extensions\$EdgeId\policy" $IngestKey $MachineId
# Firefox
# Force-install via Extensions\Install to avoid overwriting ExtensionSettings (a single JSON value that may conflict with MDM)
$FirefoxInstall = "HKLM:\SOFTWARE\Policies\Mozilla\Firefox\Extensions\Install"
if (-not (Test-Path $FirefoxInstall)) {
New-Item -Path $FirefoxInstall -Force | Out-Null
}
Set-ItemProperty -Path $FirefoxInstall -Name "1000" -Value "https://addons.mozilla.org/firefox/downloads/latest/velatir/latest.xpi" -Type String
Set-ManagedPolicy "HKLM:\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\$FirefoxId" $IngestKey $MachineId
# Vivaldi (Chromium-based; reads ExtensionInstallForcelist + 3rdparty\extensions\\policy)
$VivaldiForcelist = "HKLM:\SOFTWARE\Policies\Vivaldi\ExtensionInstallForcelist"
if (-not (Test-Path $VivaldiForcelist)) {
New-Item -Path $VivaldiForcelist -Force | Out-Null
}
Set-ItemProperty -Path $VivaldiForcelist -Name "1000" -Value "$VivaldiId;https://clients2.google.com/service/update2/crx" -Type String
Set-ManagedPolicy "HKLM:\SOFTWARE\Policies\Vivaldi\3rdparty\extensions\$VivaldiId\policy" $IngestKey $MachineId
# Brave (Chromium-based; the policy root drops the "-Browser" suffix even
# though the install directory is "Brave-Browser")
$BraveForcelist = "HKLM:\SOFTWARE\Policies\BraveSoftware\Brave\ExtensionInstallForcelist"
if (-not (Test-Path $BraveForcelist)) {
New-Item -Path $BraveForcelist -Force | Out-Null
}
Set-ItemProperty -Path $BraveForcelist -Name "1000" -Value "$BraveId;https://clients2.google.com/service/update2/crx" -Type String
Set-ManagedPolicy "HKLM:\SOFTWARE\Policies\BraveSoftware\Brave\3rdparty\extensions\$BraveId\policy" $IngestKey $MachineId
Write-Output "Velatir browser extensions configured (machineId: $MachineId)"
```
To deploy to a subset of browsers, comment out the corresponding section in both the configuration and uninstall scripts.
### Uninstall
This reverses everything the configuration script writes. It is safe to run either way, and leaves MDM-managed policies (at forcelist indexes other than `1000`) untouched.
**Uninstall script** (`Remove-Velatir.ps1`):
```powershell expandable theme={null}
$ChromeId = "bbiokppljpbjgiogcoggjnfffbeiihja"
$EdgeId = "phgnjcoglpdamjjmidheehacjbkgkooc"
$FirefoxId = "velatir@velatir.com"
$VivaldiId = $ChromeId
$BraveId = $ChromeId
function Remove-ForcelistEntry($Path, $Name) {
if (Test-Path $Path) {
Remove-ItemProperty -Path $Path -Name $Name -ErrorAction SilentlyContinue
}
}
# Chrome
Remove-ForcelistEntry "HKLM:\SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist" "1000"
Remove-Item -Path "HKLM:\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\$ChromeId" -Recurse -Force -ErrorAction SilentlyContinue
# Edge
Remove-ForcelistEntry "HKLM:\SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist" "1000"
Remove-Item -Path "HKLM:\SOFTWARE\Policies\Microsoft\Edge\3rdparty\extensions\$EdgeId" -Recurse -Force -ErrorAction SilentlyContinue
# Vivaldi
Remove-ForcelistEntry "HKLM:\SOFTWARE\Policies\Vivaldi\ExtensionInstallForcelist" "1000"
Remove-Item -Path "HKLM:\SOFTWARE\Policies\Vivaldi\3rdparty\extensions\$VivaldiId" -Recurse -Force -ErrorAction SilentlyContinue
# Brave
Remove-ForcelistEntry "HKLM:\SOFTWARE\Policies\BraveSoftware\Brave\ExtensionInstallForcelist" "1000"
Remove-Item -Path "HKLM:\SOFTWARE\Policies\BraveSoftware\Brave\3rdparty\extensions\$BraveId" -Recurse -Force -ErrorAction SilentlyContinue
# Firefox (registry)
Remove-ForcelistEntry "HKLM:\SOFTWARE\Policies\Mozilla\Firefox\Extensions\Install" "1000"
Remove-Item -Path "HKLM:\SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\$FirefoxId" -Recurse -Force -ErrorAction SilentlyContinue
# Firefox policies.json alternative: remove only Velatir entries, leave other policies intact
$PolicyFile = "C:\Program Files\Mozilla Firefox\distribution\policies.json"
if (Test-Path $PolicyFile) {
try {
$Policy = Get-Content $PolicyFile -Raw | ConvertFrom-Json -AsHashtable
if ($Policy.policies.ExtensionSettings) {
$Policy.policies.ExtensionSettings.Remove($FirefoxId)
if ($Policy.policies.ExtensionSettings.Count -eq 0) { $Policy.policies.Remove("ExtensionSettings") }
}
if ($Policy.policies."3rdparty".Extensions) {
$Policy.policies."3rdparty".Extensions.Remove($FirefoxId)
if ($Policy.policies."3rdparty".Extensions.Count -eq 0) { $Policy.policies.Remove("3rdparty") }
}
if ($Policy.policies.Count -eq 0) {
Remove-Item -Path $PolicyFile -Force
} else {
$Policy | ConvertTo-Json -Depth 10 | Set-Content -Path $PolicyFile -Encoding UTF8
}
} catch {}
}
# Legacy cleanup: earlier versions of the configuration script persisted a
# generated GUID here. Remove it if present so upgrades leave no stale data.
Remove-Item -Path "HKLM:\SOFTWARE\Velatir\BrowserExtension" -Recurse -Force -ErrorAction SilentlyContinue
$VelatirRoot = "HKLM:\SOFTWARE\Velatir"
if ((Test-Path $VelatirRoot) -and -not (Get-ChildItem $VelatirRoot -ErrorAction SilentlyContinue)) {
Remove-Item -Path $VelatirRoot -Force -ErrorAction SilentlyContinue
}
Write-Output "Velatir browser policies removed"
```
Removing the force-install policy does not uninstall the extension from existing profiles; users can then disable or remove it themselves. To force removal, block the extension first (Chrome/Edge `ExtensionInstallBlocklist`, or Firefox `ExtensionSettings` with `installation_mode: blocked`) before running the uninstall script.
If you deployed via the MSI instead, uninstall with `msiexec /x VelatirExtension-x64.msi /qn` (or `VelatirExtension-arm64.msi` for ARM64 fleets).
### Firefox via policies.json
To use a `policies.json` file instead of registry keys for Firefox, run this script in place of (or alongside) the Firefox section above.
**Configuration script** (`Configure-VelatirFirefoxJson.ps1`):
```powershell expandable theme={null}
# Configuration - UPDATE THIS VALUE
$IngestKey = "your-ingest-key-here"
# Machine ID: Windows computer name. Matches the MSI's [ComputerName] behaviour.
$MachineId = $env:COMPUTERNAME
$PolicyDir = "C:\Program Files\Mozilla Firefox\distribution"
$PolicyFile = "$PolicyDir\policies.json"
if (-not (Test-Path $PolicyDir)) {
New-Item -Path $PolicyDir -ItemType Directory -Force | Out-Null
}
# Merge with existing policies.json if present
$Policy = @{ policies = @{} }
if (Test-Path $PolicyFile) {
try {
$Policy = Get-Content $PolicyFile -Raw | ConvertFrom-Json -AsHashtable
} catch {
$Policy = @{ policies = @{} }
}
}
$Policy.policies.ExtensionSettings = @{
"velatir@velatir.com" = @{
installation_mode = "force_installed"
install_url = "https://addons.mozilla.org/firefox/downloads/latest/velatir/latest.xpi"
}
}
$Policy.policies."3rdparty" = @{
Extensions = @{
"velatir@velatir.com" = @{
apiToken = $IngestKey
machineId = $MachineId
}
}
}
$Policy | ConvertTo-Json -Depth 10 | Set-Content -Path $PolicyFile -Encoding UTF8
Write-Output "Velatir Firefox policies.json configured (machineId: $MachineId)"
```
Firefox updates may remove the `distribution` folder. If using this method, schedule the script to run regularly (e.g., once per day) to ensure the file is recreated after updates.
## Intune Settings Catalog (force-install only)
Use this to force-install the extension without pre-configured settings. Users enter the ingest key manually afterwards.
The Settings Catalog does not support Firefox. For Firefox, use the PowerShell script above.
1. Sign in to the [Microsoft Intune admin center](https://intune.microsoft.com)
2. Go to **Devices** > **Configuration** > **Create** > **New policy**
3. Select:
* **Platform**: Windows 10 and later
* **Profile type**: Settings catalog
4. Name your profile (e.g., "Velatir Chrome Extension")
5. Click **Add settings** and search for **Google Chrome**
6. Select **Google Chrome** > **Extensions**
7. Enable **Configure the list of force-installed apps and extensions**
8. Add the following value:
```
bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx
```
9. Assign to your device groups and create the profile
1. Create a new Settings catalog profile
2. Search for **Microsoft Edge** > **Extensions**
3. Enable **Control which extensions are installed silently**
4. Add the following value:
```
phgnjcoglpdamjjmidheehacjbkgkooc;https://edge.microsoft.com/extensionwebstorebase/v1/crx
```
5. Assign to your device groups
***
## Manual Registry Configuration (Windows)
Not using Intune or SCCM? Apply the same policies directly with `regedit`, Group Policy Preferences, or any tool that writes registry values. The tables below list every key, value name, and data.
All values are `REG_SZ` (String) under `HKEY_LOCAL_MACHINE` (`HKLM`). Run your tool in 64-bit context so writes don't land under `WOW6432Node`.
Use the value name `1000` for the force-install entries. This avoids colliding with MDM-managed entries, which typically start at `1`.
**Required**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `SOFTWARE\Policies\Google\Chrome\ExtensionInstallForcelist` | `1000` | `bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx` |
| `SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `apiToken` | Your organisation's ingest key (e.g. `vltr_...`) |
**Optional**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------- |
| `SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `machineId` | Stable per-device identifier (e.g. computer name) |
**Required**
| Key | Value name | Data |
| ---------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `SOFTWARE\Policies\Microsoft\Edge\ExtensionInstallForcelist` | `1000` | `phgnjcoglpdamjjmidheehacjbkgkooc;https://edge.microsoft.com/extensionwebstorebase/v1/crx` |
| `SOFTWARE\Policies\Microsoft\Edge\3rdparty\extensions\phgnjcoglpdamjjmidheehacjbkgkooc\policy` | `apiToken` | Your organisation's ingest key |
**Optional**
| Key | Value name | Data |
| ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------- |
| `SOFTWARE\Policies\Microsoft\Edge\3rdparty\extensions\phgnjcoglpdamjjmidheehacjbkgkooc\policy` | `machineId` | Stable per-device identifier |
**Required**
| Key | Value name | Data |
| --------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
| `SOFTWARE\Policies\Mozilla\Firefox\Extensions\Install` | `1000` | `https://addons.mozilla.org/firefox/downloads/latest/velatir/latest.xpi` |
| `SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\velatir@velatir.com` | `apiToken` | Your organisation's ingest key |
**Optional**
| Key | Value name | Data |
| --------------------------------------------------------------------------- | ----------- | ---------------------------- |
| `SOFTWARE\Policies\Mozilla\Firefox\3rdparty\Extensions\velatir@velatir.com` | `machineId` | Stable per-device identifier |
Vivaldi is Chromium-based and reads the standard `ExtensionInstallForcelist` and `3rdparty\extensions\\policy` keys under its own vendor namespace. It installs the Chrome Web Store build of the extension and therefore reuses Chrome's extension ID.
**Required**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `SOFTWARE\Policies\Vivaldi\ExtensionInstallForcelist` | `1000` | `bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx` |
| `SOFTWARE\Policies\Vivaldi\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `apiToken` | Your organisation's ingest key |
**Optional**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------- | ----------- | ---------------------------- |
| `SOFTWARE\Policies\Vivaldi\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `machineId` | Stable per-device identifier |
Brave's install directory is `Brave-Browser` but the documented *policy* root drops the suffix and lives at `SOFTWARE\Policies\BraveSoftware\Brave`. It installs the Chrome Web Store build of the extension and therefore reuses Chrome's extension ID.
**Required**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `SOFTWARE\Policies\BraveSoftware\Brave\ExtensionInstallForcelist` | `1000` | `bbiokppljpbjgiogcoggjnfffbeiihja;https://clients2.google.com/service/update2/crx` |
| `SOFTWARE\Policies\BraveSoftware\Brave\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `apiToken` | Your organisation's ingest key |
**Optional**
| Key | Value name | Data |
| --------------------------------------------------------------------------------------------------- | ----------- | ---------------------------- |
| `SOFTWARE\Policies\BraveSoftware\Brave\3rdparty\extensions\bbiokppljpbjgiogcoggjnfffbeiihja\policy` | `machineId` | Stable per-device identifier |
To remove the configuration, delete the values you added. This does not uninstall the extension from existing profiles; users can then disable or remove it themselves.
***
Browser support, managed config, and other platforms
Confirm policies applied and the extension is installed
# Escalations
Source: https://docs.velatir.com/traces/escalations
Bring a person in when a trace needs human judgment.
## What Is an Escalation?
Most traces are handled by your agents without anyone needing to step in. An escalation is what happens when a trace needs a person: Velatir notifies the right people through your connected channels and records their response.
This is the human oversight that regulations expect, applied only where it matters so your team is not flooded with noise.
## When a Trace Is Escalated
An Enforcer escalates a trace when it has a concern that warrants approval rather than a hard block, typically a high-criticality finding. The trace is held for a person to review. You decide which findings are high criticality through your [Data Protector categories](/agents/data-protector) and your [instructions](/agents/instructions).
## Connect a Channel
Escalations are sent to the channels you connect under **Settings → Channels**.
Add Velatir to the Slack channel where your reviewers work, and escalations arrive there.
![Adding Velatir to a Slack channel]()
Connect a Teams channel so escalations reach your reviewers where they already collaborate.
Add a phone number for the highest-priority escalations that should not wait.
## Escalation Status
Every escalation tracks where it stands, so nothing is missed.
| Status | Meaning |
| ---------------- | ------------------------------------------------------ |
| **Sent** | The escalation was delivered to your channels. |
| **Acknowledged** | Someone has seen it and is handling it. |
| **Resolved** | A decision has been made and the escalation is closed. |
Every escalation, who responded, and the decision they made are recorded in the audit trail.
***
Where escalation fits in a trace's journey.
Set which findings are high criticality.
# Trace Lifecycle
Source: https://docs.velatir.com/traces/trace-lifecycle
How a trace flows through Velatir from capture to final state.
## Overview
Every AI interaction captured by Velatir follows the same path. Understanding it helps you read trace outcomes and configure your agents well.
## The Stages
The browser extension or desktop app sends an interaction to Velatir. The trace is stored and grouped into a session with any related traces. Review begins straight away.
Both active agents review the trace at the same time, each recording an assessment.
| Agent | Looks at |
| ------------------ | ------------------------------------------------------------------------ |
| **Gatekeeper** | Which service is being used |
| **Data Protector** | Sensitive content such as credentials, personal data, and financial data |
Each agent reaches a verdict based on your configuration.
The outcome depends on each agent's role.
| Role | What it can do |
| ------------ | ----------------------------------------------------------- |
| **Observer** | Flags its finding for review. Does not block or notify. |
| **Enforcer** | Blocks the trace, or escalates it to a person for approval. |
The most restrictive outcome wins. If either agent blocks, the trace is blocked. If either escalates, it is escalated.
The trace settles as one of four outcomes: **Allowed**, **Flagged**, **Blocked**, or **Escalated**. Escalations notify your team but do not change the outcome of the trace itself.
## Sessions Give Context
Related traces are grouped into a session that represents a complete conversation or workflow. When a reviewer looks at an escalated trace, they see the whole session around it rather than a single interaction on its own.
## Monitoring
* **Sessions** shows activity grouped into complete interactions.
* **Assessments** shows every agent verdict, with reasoning and any applied instruction.
* Open any trace to see each agent's assessment, how the outcome was resolved, and any escalation.
***
What happens when a trace needs a person.
How traces are grouped into sessions.
# Traces
Source: https://docs.velatir.com/traces/traces
Traces are the individual interactions within a session that Velatir captures and reviews.
## What Is a Trace?
A trace is a single AI interaction captured within a [session](/traces/understanding-sessions). Every request sent to an AI service, every response received, and every related event creates a trace.
Traces are the raw material agents review. Each one records what happened, where it came from, and what the outcome was.
## Trace Directions
Every trace has a direction that describes the type of interaction.
| Direction | Description | Example |
| ------------ | -------------------------------------- | -------------------------------------------- |
| **Inlet** | A request going to an AI service | Someone submits a prompt to a chat assistant |
| **Response** | A reply coming back from an AI service | The assistant's answer |
| **Signal** | A related event | A session starting, or a background event |
## Viewing a Trace
Within a session, select any trace to see its full details.
* **Direction and source** show the type of interaction and which service was involved.
* **Assessments** show what each agent found and the verdict it reached.
* **Outcome** shows whether the trace was allowed, flagged, blocked, or escalated.
* **Escalations** show where a trace was sent and its status, when applicable.
## What Happens After Capture
Your active agents review the trace, each recording its own assessment.
Based on the agents' findings and their roles, the trace is allowed, flagged, blocked, or escalated. The most restrictive outcome wins.
The trace reaches its final state and is recorded. Escalations are sent to your connected channels.
For the full picture, see [Trace lifecycle](/traces/trace-lifecycle).
***
How traces are grouped into sessions.
Follow a trace from capture to final state.
# Understanding Sessions
Source: https://docs.velatir.com/traces/understanding-sessions
Sessions group related traces into a complete interaction, your main view into AI activity.
## What Is a Session?
A session is a complete AI interaction. When someone chats with an AI assistant, runs a multi-step automation, or uses an AI-powered tool, Velatir captures the whole exchange as a session.
Sessions are the main way you monitor AI usage. Each session contains one or more **traces**, the individual requests, responses, and events that make up the interaction.
## How Sessions Work
Someone starts using an AI service, for example opening a conversation or triggering an AI-powered workflow.
Each request, response, and event is captured as a trace and grouped into the session automatically.
As traces arrive, your active agents review each one. The session view shows the overall state and highlights anything that was flagged.
The session shows when a trace needs attention, such as one escalated for review, and settles once it is resolved.
## Viewing Sessions
In the dashboard, open **Sessions** to see activity across your workspaces.
* Filter by service, status, origin, and more, and save views you return to often.
* Open a session to see its traces in order.
* Select a trace to see each agent's assessment and the outcome.
***
Trace directions, details, and outcomes.
Follow a trace from capture to final state.