Install TruVelocity™ for AI TEVV on your laptop
Install with pip into a private Python environment and open
the TruVelocity UI in your browser. No Docker, no LLM and no API keys are needed for the first run, and nothing needs
admin rights. About 10 minutes.
The expected outputs on this page were recorded on Windows 11 with Python 3.12.10 and release 2026.11.18.2, installed from PyPI.
What you get
- The
tvcommand (long formtruvelocity-tevv): validate test catalogs, run them against an agent, read the results, and apply the release gate. - The TruVelocity UI (
tv ui): the six-step wizard in your browser, served from your own laptop on127.0.0.1with a one-time key in the URL. - The console (
tv console): browse runs, reports, defects, scorecards and gates. - An offline tour (
tv demo) and a starter project (tv new), both shipped in the package. - Optional: the MCP server (
tv mcp) so an AI assistant can drive TruVelocity for you.
Everything runs on your laptop. Nothing is sent anywhere unless you publish a run yourself (tv push).
Prerequisites
| You need | Details |
|---|---|
| Python 3.11 or 3.12 | The package requires Python 3.11 or later and is tested on 3.11 and 3.12. Windows: install from
python.org (tick Add python.exe to PATH or use the py launcher). macOS: python.org installer or Homebrew.
Linux: your distribution's python3; on Debian or Ubuntu also the python3-venv package. |
| pip | Comes with Python. Step 2 upgrades it inside the virtual environment. |
| Disk | About 30 MB for the virtual environment with the UI extra (26 MB measured), plus space for your runs. |
| Network | HTTPS access to pypi.org and files.pythonhosted.org (or your company's PyPI mirror)
while you install. After that, the tour, the starter project and the UI work offline. |
| Admin rights | Not needed. Everything installs into a folder you own. (Only installing Python itself, or
python3-venv on Linux, may need them; ask IT if Python is missing.) |
| A browser | Any current Edge, Chrome, Firefox or Safari. |
1Create a project folder and a virtual environment
A virtual environment keeps TruVelocity and its few dependencies in one folder (.venv), apart from any other Python on your laptop.
# create a working folder
mkdir truvelocity# go into it
cd truvelocity# create the virtual environment with Python 3.12 (use -3.11 for 3.11)
py -3.12 -m venv .venv# activate it: the prompt then starts with (.venv)
.venv\Scripts\Activate.ps1Activate.ps1.
Allow scripts for this window only (no admin rights, nothing changes permanently), then run step 4 again:# allow scripts in this PowerShell window only
Set-ExecutionPolicy -Scope Process -ExecutionPolicy BypassIf your company policy forbids even that, use Windows cmd instead, or skip activation and call the tools by path:
.venv\Scripts\python -m pip ... and .venv\Scripts\tv ....
rem create a working folder
mkdir truvelocityrem go into it
cd truvelocityrem create the virtual environment with Python 3.12 (use -3.11 for 3.11)
py -3.12 -m venv .venvrem activate it: the prompt then starts with (.venv)
.venv\Scripts\activate.bat# create a working folder
mkdir truvelocity# go into it
cd truvelocity# create the virtual environment (python3 must be 3.11 or later: check with python3 --version)
python3 -m venv .venv# activate it: the prompt then starts with (.venv)
source .venv/bin/activateIf python3 is older than 3.11, name a newer one explicitly, for example python3.12 -m venv .venv.
On Debian or Ubuntu, "ensurepip is not available" means the python3-venv package is missing.
No py launcher on Windows? Use python -m venv .venv instead, after checking that
python --version says 3.11 or 3.12.
2Install TruVelocity
Inside the activated environment (the commands are the same on every system from here on, apart from paths).
# bring pip up to date inside the environment
python -m pip install --upgrade pip# install TruVelocity with the UI extra
pip install "truvelocity-tevv[ui]"rem bring pip up to date inside the environment
python -m pip install --upgrade piprem install TruVelocity with the UI extra
pip install "truvelocity-tevv[ui]"# bring pip up to date inside the environment
python -m pip install --upgrade pip# install TruVelocity with the UI extra (the quotes stop zsh expanding the brackets)
pip install "truvelocity-tevv[ui]"Successfully installed attrs-26.1.0 et-xmlfile-2.0.0 jsonschema-4.26.0 jsonschema-specifications-2025.9.1 openpyxl-3.1.5 pyyaml-6.0.3 referencing-0.37.0 rpds-py-2026.9.1 truvelocity-tevv-2026.11.18.2 typing-extensions-4.16.0
The dependency versions may differ on your day; truvelocity-tevv-2026.11.18.2 (or later) is what matters.
Extras
The core install is small (PyYAML and jsonschema). Extras add optional features; combine them with commas, for example
pip install "truvelocity-tevv[ui,mcp]".
| Extra | Adds |
|---|---|
ui | Reading the Context workbook (.xlsx) in tv ui. The UI starts without it, but install it for the full wizard. |
mcp | The MCP server, tv mcp (see the README for client set-up). |
chat, langgraph | The WebSocket chat driver; LangGraph support. |
proxy, otel | The recording proxy and agent-to-agent tap (tv proxy, tv a2a); the OpenTelemetry receiver (tv otel). |
azure, anthropic | The LLM grader. |
sql, postgres, sqlserver, mysql, oracle, s3, azure-blob, servicebus, kafka | Databases, shared stores and message queues. |
The full list is in the README. dev is for people working on TruVelocity itself, not for users.
3Check the install
# print the installed version
tv --versionrem print the installed version
tv --version# print the installed version
tv --versionTruVelocity for AI TEVV 2026.11.18.2
To see every command:
# list the commands
tv --helpusage: tv [-h] [--version] command ...
TruVelocity for AI TEVV: evidence-based quality engineering for AI agents.
positional arguments:
command
demo the offline tour: every feature on a scripted agent (no Docker,
no LLM)
new create a starter project: catalog, environment factory, gate,
settings
docs write the TruVelocity guide (getting started, catalogs,
commands) and open it
...
console browse runs, reports and gates in a browser (local, token-
protected)
ui the TruVelocity wizard in a browser over this project's agents
(local, token-protected)
...tv --version prints 2026.11.18.2 or later. truvelocity-tevv --version prints the same.4First run: pick one
| Option | What you see | Available |
|---|---|---|
| A. Demo project | The UI over three sample agents with run history; runs can be started from the browser. Offline: no Docker, no LLM. | Release 2026.11.19.1 or later |
| B. UI prototype with sample data | The UI with sample agents, read-only. Writes nothing to disk. | Today (2026.11.18.2) |
| C. Offline tour, then the console | Real runs against a scripted agent (passes, a planted failure, gate, reports), browsed in the console. | Today (2026.11.18.2) |
A. The demo project NEXT RELEASE
Creates a folder (default truvelocity-demo) with three sample agents and their run history, all offline, then opens the UI on it.
# create the offline demo project
tv demo-project# go into it
cd truvelocity-demo# start the UI, allow runs from the browser, and open it
tv ui --allow-runs --openrem create the offline demo project
tv demo-projectrem go into it
cd truvelocity-demorem start the UI, allow runs from the browser, and open it
tv ui --allow-runs --open# create the offline demo project
tv demo-project# go into it
cd truvelocity-demo# start the UI, allow runs from the browser, and open it
tv ui --allow-runs --openTruVelocity demo project in truvelocity-demo: three agents, their catalogs and four weeks of runs claims-20261024-091204 claims build 3.0.0 chat-20261025-100531 chat build 2.1.0 desk-20261026-144012 desk build 1.0.0 claims-20261031-092045 claims build 3.0.1 chat-20261101-113009 chat build 2.2.0 desk-20261103-150552 desk build 1.1.0 claims-20261107-090817 claims build 3.1.0 chat-20261110-104540 chat build 2.3.0 desk-20261111-161026 desk build 1.2.0 desk-20261116-132503 desk build 1.2.1 claims-20261117-091538 claims build 3.1.1 chat-20261118-174011 chat build 2.4.0 made 12 runs in 3 s; latest verdicts: Claims back-office agent Go 100% of cases passed every try; defects: 0 critical, 0 major, 0 minor Customer chat assistant No-go 67% of cases passed every try; defects: 1 critical, 1 major, 1 minor Member service desk Go 100% of cases passed every try; defects: 0 critical, 0 major, 0 minor next: cd truvelocity-demo tv ui --allow-runs --open
To use another folder name: tv demo-project my-demo.
B. The UI prototype with sample data WORKS TODAY
# the UI with sample agents (no project needed); opens your browser
tv ui --demo --openrem the UI with sample agents (no project needed); opens your browser
tv ui --demo --open# the UI with sample agents (no project needed); opens your browser
tv ui --demo --openTruVelocity UI (demo): http://127.0.0.1:8770/?t=t1XiobdgOG0ka7NGkp3E03U3pdWkLVIw (the token in the URL is your key; Ctrl+C stops it)
Read-only sample data: good for a look around the six steps. It writes no files in the folder you start it from.
C. The offline tour, then the console WORKS TODAY
Runs every feature against a scripted agent shipped in the package, into a tv_demo folder (about a minute), then shows the runs in the browser.
# the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demo# browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --openrem the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demorem browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --open# the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demo# browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --openTruVelocity 2026.11.18.2: offline demo into tv_demo (no agent, no Docker, no LLM)
== 1. Check the catalog against the schema
OK tv_demo\demo-catalog.yaml (2 scenarios)
demo-a: 3 pass, 0 fail, 0 flaky of 3 cases
demo-b: 3 pass, 0 fail, 0 flaky of 3 cases
demo-fail: 2 pass, 1 fail, 0 flaky of 3 cases
gate demo-fail (default policy): FAIL
...
== Next
open a report: tv_demo\demo-fail\execution-report.html (customer-facing)
tv_demo\demo-fail\report.html (engineering)TruVelocity console: http://127.0.0.1:8765/?t=-k9rnpM3H1zpRgEHYrseuRoWhPiSm4yP (the token in the URL is your key; Ctrl+C stops the console)
The gate is meant to say FAIL: the tour plants a defect so you can see how a failure is reported. Each report is a single HTML file that also opens straight from the folder.
5Open the UI, and stop it
- The URL carries a one-time key.
tv uiprints a link such ashttp://127.0.0.1:8770/?t=.... With--openyour browser opens it for you; otherwise copy the whole link, including?t=.... The browser keeps the key in a cookie for that session, and the address bar then shows justhttp://127.0.0.1:8770/. - A welcome page first. The first page in each new browser session (and after you sign out) is a sign-in page: click Explore as demo user (or sign in with any email) to go in; nothing typed there is stored.
- A new key every start. After you restart
tv ui, old links and bookmarks no longer work: use the new link it prints. - This laptop only. The UI listens on
127.0.0.1(loopback), so no one else on the network can reach it.--allow-runslets the browser start runs, and only from the presets intv-console.yaml. - Default ports:
tv ui8770,tv console8765. Choose another with--listen 127.0.0.1:PORT. - Stop it with Ctrl+C in the terminal window where it runs (closing the browser tab does not stop it).
# the same UI on port 8790
tv ui --demo --listen 127.0.0.1:8790 --openOpening the address without the key, or with an old key, shows a forbidden page:
console forbidden local · token-protected Open the console with the URL it printed (it carries a one-time token).
6Use it on your own agent
In brief; the README and the built-in guide (tv docs --open) have the details.
- Create a starter project for your kind of agent:
task,workflow(multi-agent) orchat.
# a starter project for a task agent, in the folder my-agent
tv new task my-agentrem a starter project for a task agent, in the folder my-agent
tv new task my-agent# a starter project for a task agent, in the folder my-agent
tv new task my-agentcreated a task project in my-agent: catalog.yaml environment.py README.md .env.example truvelocity-tevv-gate.yaml truvelocity-tevv.yaml .gitignore tv-console.yaml next: cd my-agent copy .env.example to .env and set the agent's URL and data paths edit catalog.yaml, then: tv validate catalog.yaml tv run catalog.yaml --env environment:environment or, from the browser: tv console --allow-runs --open (presets in tv-console.yaml) (README.md has every step; tv docs --open has the guide)
- Point it at your agent: copy
.env.exampleto.envand setTV_AGENT_URLand the agent's data paths..envstays on your laptop and TruVelocity never prints it. - Write the test catalog (
catalog.yaml: the scenarios), check it, and run it:
# go into the project
cd my-agent# check the catalog against the schema
tv validate catalog.yaml# run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environmentrem go into the project
cd my-agentrem check the catalog against the schema
tv validate catalog.yamlrem run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environment# go into the project
cd my-agent# check the catalog against the schema
tv validate catalog.yaml# run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environment- Reuse ready-made scenarios:
tv librarylists the scenario packs (privacy, prompt injection and more). - Run from the browser:
tv console --allow-runs --openstarts runs from the presets intv-console.yaml. - Show it in the UI:
tv uireads the agents to show fromtv-ui.yaml, whichtv newwrites from release 2026.11.19.1 (one agent, from the project's preset). On an older release, add one next totv-console.yaml; each agent names a preset from that file:
agents:
task:
name: My agent
kind: task
preset: task
environment: my agent over HTTP# the wizard over the agents in tv-ui.yaml; the browser may start runs
tv ui --allow-runs --openWithout tv-ui.yaml, tv ui stops with: tv ui: cannot read tv-ui.yaml: ... (list the agents to show in tv-ui.yaml, or use --demo for the sample agents).
To gate a CI pipeline on a catalog later, tv init --ci github --catalog catalog.yaml --env environment:environment (or --ci azure) writes the pipeline file; see the README.
7Optional: the live demo agents (Docker and an LLM) ADVANCED
The sample agents behind the TruVelocity demos (the fictitious Harbor Mutual customer chat, claims agent and member desk) can run for real on your laptop. This is not needed to use TruVelocity on your own agent, and it is not a pip-only path.
| You need | Why |
|---|---|
| Docker Desktop (or Docker Engine on Linux), running | The agents run as container images published from the public
SystemsUnderTest repository (ghcr.io/shankonduru/...).
Docker Desktop in a company may need a licence and admin rights to install. |
| A checkout of the TruVelocity repository and of SystemsUnderTest, side by side | The live catalogs (pilots/), the presets
and the start-up scripts are in the repository, not in the pip package. Ask your Innominds contact for access. |
An LLM provider key, in a .env file | The agents call an LLM. Copy .env.example to .env, set
DEFAULT_LLM_PROVIDER (AZURE, ANTHROPIC, OPENAI, OLLAMA, OPENAI_COMPATIBLE,
BEDROCK, GEMINI, VERTEX or SCRIPTED) and only that provider's settings, for example
AZURE_API_KEY, AZURE_ENDPOINT, AZURE_DEPLOYMENT, AZURE_API_VERSION. Usage is billed by your provider. |
From the repository, scripts\truvelocity-tevv-ops.bat help (or sh scripts/truvelocity-tevv-ops.sh help) lists the commands
that deploy the agents (deploy all, status) and run the live pilots; scripts/dev_deploy.* starts the UI
from the checkout and scripts/docker_deploy.* runs the UI itself in Docker. The repository's README and
demo runbook walk through it. This guide does not repeat those steps.
8Upgrade, pin a version, uninstall
Activate the environment first (section 1, step 4). Versions follow the release date, YYYY.M.D.N
(N counts the builds released that day), so a later date is always newer.
# move to the newest release (keep the extras you use)
pip install --upgrade "truvelocity-tevv[ui]"# install exactly one release, for repeatable results across a team
pip install "truvelocity-tevv[ui]==2026.11.18.2"# which releases PyPI has
pip index versions truvelocity-tevvtruvelocity-tevv (2026.11.18.2) Available versions: 2026.11.18.2, 2026.11.18.1, 2026.11.17.2, 2026.11.17.1
# remove the package from this environment
pip uninstall truvelocity-tevvTo remove everything, deactivate (deactivate) and delete the .venv folder. Your projects and runs
(tv_runs, tv_demo, your catalogs) are ordinary folders: keep or delete them as you like.
9Troubleshooting
| Symptom | What to do |
|---|---|
python or py is not recognised; or typing python opens the Microsoft Store |
Python is not installed or not on the PATH. Install Python 3.12 from python.org (no admin needed with "Install for me only"), then open a new terminal. To stop the Store prompt: Settings > Apps > Advanced app settings > App execution aliases, turn off python.exe and python3.exe. |
Wrong Python version; pip says requires a different Python or No matching distribution found for truvelocity-tevv |
The environment was made with Python older than 3.11. Check with python --version inside it; delete .venv and recreate it
with py -3.12 -m venv .venv (Windows) or python3.12 -m venv .venv (macOS / Linux). py -0 lists the Pythons the Windows launcher knows. |
| pip times out or cannot connect, behind a corporate proxy | Give pip the proxy: pip install --proxy http://proxy.example.com:8080 "truvelocity-tevv[ui]", or set
HTTPS_PROXY for the session. If your company has an internal PyPI mirror, use
pip install --index-url https://your-mirror/simple "truvelocity-tevv[ui]". |
SSL: CERTIFICATE_VERIFY_FAILED (SSL inspection) |
Your network re-signs HTTPS with a company certificate. Ask IT for the company root certificate (a .pem file) and point pip at it:
pip config set global.cert C:\path\to\company-ca.pem (or set PIP_CERT). Avoid --trusted-host: it turns off
verification. |
tv is not recognised / command not found |
The environment is not active in this terminal (each new window needs step 4 again), or the install failed. Activate it, or call it by path:
.venv\Scripts\tv --version (Windows) or .venv/bin/tv --version (macOS / Linux). python -m pip show truvelocity-tevv tells you whether it is installed. |
Activate.ps1 cannot be loaded ... running scripts is disabled |
Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in that window (section 1), or use Windows cmd. |
invalid choice: 'demo-project' | Your release is older than the one that adds it (2026.11.19.1 or later). Upgrade (section 8) or use first-run option B or C. |
tv ui: cannot read tv-ui.yaml | You started tv ui outside a project that lists agents. Use tv ui --demo, start it in the demo project, or add a tv-ui.yaml (section 6). |
| Port already in use, or the page shows a different app | Something else uses 8770 (or 8765). Start on another port: tv ui --listen 127.0.0.1:8790 --open. Stop an old TruVelocity window with Ctrl+C first.
Before release 2026.11.19.1, a second server on Windows could start on a port that was already taken, without any error; from that release it stops at once with an error, so if the page looks wrong on an older release, close the other terminal or change the port. |
| The browser shows forbidden / a token error | The link has no key or an old one. Copy the whole link from the latest start, including ?t=...; restarting creates a new key.
Use the same browser profile; if it still fails, open the link in a private window. |
Access is denied / PermissionError on a temporary folder during install or a run |
Company policy may lock your temp folder or the folder you work in. Work in a folder under your user profile (for example Documents\truvelocity), not under
Program Files or a synced/network drive, and point temp at a folder you own for the session:
PowerShell $env:TEMP="$HOME\tvtemp"; $env:TMP=$env:TEMP (create the folder first). |
Install or first start is very slow; tv.exe is blocked or quarantined |
Antivirus scans every new file in the environment and may flag the small tv.exe launcher pip creates. Wait for the first scan, or ask IT to allow the
project folder. Meanwhile python -m truvelocity_tevv.core.cli --version runs the same command without the launcher. |
Corporate laptops: a short checklist
- No admin rights needed once Python is installed; everything lives in your project folder.
- Network: allow
pypi.organdfiles.pythonhosted.org, or use the company PyPI mirror; set the proxy and company certificate for pip (section 9). - PowerShell policy: use the per-window
Set-ExecutionPolicy -Scope Process, or cmd. - Data stays local: the UI and console listen on
127.0.0.1only and need the one-time key; nothing is uploaded unless you runtv push. Secrets go in.env, which the starter's.gitignoreexcludes. - Firewall prompts: none are expected, because nothing listens on the network; if one appears, you can decline it.
- Docker and LLM keys are only for the optional live demo (section 7) and follow your company's software and data policies.
Related: PyPI validation runbook (a full check of a release from pip) · README · what has been validated.