TruVelocity™ for AI TEVVLocal install guide

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.

Windows · macOS · LinuxPython 3.11 or 3.12 no admin rightsworks offline after installloopback only
Show commands for:

What you get

  • The tv command (long form truvelocity-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 on 127.0.0.1 with 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 needDetails
Python 3.11 or 3.12The 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.
pipComes with Python. Step 2 upgrades it inside the virtual environment.
DiskAbout 30 MB for the virtual environment with the UI extra (26 MB measured), plus space for your runs.
NetworkHTTPS 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 rightsNot 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 browserAny 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.

Windows PowerShell · 1/7
# create a working folder
mkdir truvelocity
Windows PowerShell · 2/7
# go into it
cd truvelocity
Windows PowerShell · 3/7
# create the virtual environment with Python 3.12 (use -3.11 for 3.11)
py -3.12 -m venv .venv
Windows PowerShell · 4/7
# activate it: the prompt then starts with (.venv)
.venv\Scripts\Activate.ps1
"running scripts is disabled on this system"? PowerShell's execution policy blocks Activate.ps1. Allow scripts for this window only (no admin rights, nothing changes permanently), then run step 4 again:
Windows PowerShell · 4/7 (if blocked)
# allow scripts in this PowerShell window only
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

If 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 ....

Windows cmd · 1/7
rem create a working folder
mkdir truvelocity
Windows cmd · 2/7
rem go into it
cd truvelocity
Windows cmd · 3/7
rem create the virtual environment with Python 3.12 (use -3.11 for 3.11)
py -3.12 -m venv .venv
Windows cmd · 4/7
rem activate it: the prompt then starts with (.venv)
.venv\Scripts\activate.bat
macOS / Linux · 1/7
# create a working folder
mkdir truvelocity
macOS / Linux · 2/7
# go into it
cd truvelocity
macOS / Linux · 3/7
# create the virtual environment (python3 must be 3.11 or later: check with python3 --version)
python3 -m venv .venv
macOS / Linux · 4/7
# activate it: the prompt then starts with (.venv)
source .venv/bin/activate

If 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).

Windows PowerShell · 5/7
# bring pip up to date inside the environment
python -m pip install --upgrade pip
Windows PowerShell · 6/7
# install TruVelocity with the UI extra
pip install "truvelocity-tevv[ui]"
Windows cmd · 5/7
rem bring pip up to date inside the environment
python -m pip install --upgrade pip
Windows cmd · 6/7
rem install TruVelocity with the UI extra
pip install "truvelocity-tevv[ui]"
macOS / Linux · 5/7
# bring pip up to date inside the environment
python -m pip install --upgrade pip
macOS / Linux · 6/7
# install TruVelocity with the UI extra (the quotes stop zsh expanding the brackets)
pip install "truvelocity-tevv[ui]"
expected (last line)
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]".

ExtraAdds
uiReading the Context workbook (.xlsx) in tv ui. The UI starts without it, but install it for the full wizard.
mcpThe MCP server, tv mcp (see the README for client set-up).
chat, langgraphThe WebSocket chat driver; LangGraph support.
proxy, otelThe recording proxy and agent-to-agent tap (tv proxy, tv a2a); the OpenTelemetry receiver (tv otel).
azure, anthropicThe LLM grader.
sql, postgres, sqlserver, mysql, oracle, s3, azure-blob, servicebus, kafkaDatabases, 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

Windows PowerShell · 7/7
# print the installed version
tv --version
Windows cmd · 7/7
rem print the installed version
tv --version
macOS / Linux · 7/7
# print the installed version
tv --version
expected
TruVelocity for AI TEVV 2026.11.18.2

To see every command:

any system · optional
# list the commands
tv --help
expected (first lines)
usage: 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)
    ...
Done when: tv --version prints 2026.11.18.2 or later. truvelocity-tevv --version prints the same.

4First run: pick one

OptionWhat you seeAvailable
A. Demo projectThe 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 dataThe UI with sample agents, read-only. Writes nothing to disk.Today (2026.11.18.2)
C. Offline tour, then the consoleReal 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

Needs release 2026.11.19.1 or later. On 2026.11.18.2, tv demo-project answers invalid choice: 'demo-project'; use option B or C until then, or upgrade (section 8).

Creates a folder (default truvelocity-demo) with three sample agents and their run history, all offline, then opens the UI on it.

Windows PowerShell · demo project 1/3
# create the offline demo project
tv demo-project
Windows PowerShell · demo project 2/3
# go into it
cd truvelocity-demo
Windows PowerShell · demo project 3/3
# start the UI, allow runs from the browser, and open it
tv ui --allow-runs --open
Windows cmd · demo project 1/3
rem create the offline demo project
tv demo-project
Windows cmd · demo project 2/3
rem go into it
cd truvelocity-demo
Windows cmd · demo project 3/3
rem start the UI, allow runs from the browser, and open it
tv ui --allow-runs --open
macOS / Linux · demo project 1/3
# create the offline demo project
tv demo-project
macOS / Linux · demo project 2/3
# go into it
cd truvelocity-demo
macOS / Linux · demo project 3/3
# start the UI, allow runs from the browser, and open it
tv ui --allow-runs --open
Expected output of tv demo-project (run names carry dates counted back from today, so yours differ)
TruVelocity 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

Windows PowerShell · prototype 1/1
# the UI with sample agents (no project needed); opens your browser
tv ui --demo --open
Windows cmd · prototype 1/1
rem the UI with sample agents (no project needed); opens your browser
tv ui --demo --open
macOS / Linux · prototype 1/1
# the UI with sample agents (no project needed); opens your browser
tv ui --demo --open
expected (your token differs)
TruVelocity 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.

Windows PowerShell · tour 1/2
# the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demo
Windows PowerShell · tour 2/2
# browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --open
Windows cmd · tour 1/2
rem the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demo
Windows cmd · tour 2/2
rem browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --open
macOS / Linux · tour 1/2
# the offline tour: runs, a planted failure, compare, scorecard, gate, reports
tv demo
macOS / Linux · tour 2/2
# browse the tour's runs and reports in the console
tv console --runs-dir tv_demo --open
expected from tv demo (key lines; paths use / on macOS and Linux)
TruVelocity 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)
expected from tv console (your token differs)
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 ui prints a link such as http://127.0.0.1:8770/?t=.... With --open your 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 just http://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-runs lets the browser start runs, and only from the presets in tv-console.yaml.
  • Default ports: tv ui 8770, tv console 8765. 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).
any system · another port
# the same UI on port 8790
tv ui --demo --listen 127.0.0.1:8790 --open

Opening the address without the key, or with an old key, shows a forbidden page:

expected page text without a valid key
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.

  1. Create a starter project for your kind of agent: task, workflow (multi-agent) or chat.
Windows PowerShell · own agent 1/4
# a starter project for a task agent, in the folder my-agent
tv new task my-agent
Windows cmd · own agent 1/4
rem a starter project for a task agent, in the folder my-agent
tv new task my-agent
macOS / Linux · own agent 1/4
# a starter project for a task agent, in the folder my-agent
tv new task my-agent
expected
created 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)
  1. Point it at your agent: copy .env.example to .env and set TV_AGENT_URL and the agent's data paths. .env stays on your laptop and TruVelocity never prints it.
  2. Write the test catalog (catalog.yaml: the scenarios), check it, and run it:
Windows PowerShell · own agent 2/4
# go into the project
cd my-agent
Windows PowerShell · own agent 3/4
# check the catalog against the schema
tv validate catalog.yaml
Windows PowerShell · own agent 4/4
# run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environment
Windows cmd · own agent 2/4
rem go into the project
cd my-agent
Windows cmd · own agent 3/4
rem check the catalog against the schema
tv validate catalog.yaml
Windows cmd · own agent 4/4
rem run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environment
macOS / Linux · own agent 2/4
# go into the project
cd my-agent
macOS / Linux · own agent 3/4
# check the catalog against the schema
tv validate catalog.yaml
macOS / Linux · own agent 4/4
# run it against your agent (needs the agent running at TV_AGENT_URL)
tv run catalog.yaml --env environment:environment
  1. Reuse ready-made scenarios: tv library lists the scenario packs (privacy, prompt injection and more).
  2. Run from the browser: tv console --allow-runs --open starts runs from the presets in tv-console.yaml.
  3. Show it in the UI: tv ui reads the agents to show from tv-ui.yaml, which tv new writes from release 2026.11.19.1 (one agent, from the project's preset). On an older release, add one next to tv-console.yaml; each agent names a preset from that file:
tv-ui.yaml · minimal example (tested with the task starter)
agents:
  task:
    name: My agent
    kind: task
    preset: task
    environment: my agent over HTTP
any system · UI on your project
# the wizard over the agents in tv-ui.yaml; the browser may start runs
tv ui --allow-runs --open

Without 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 needWhy
Docker Desktop (or Docker Engine on Linux), runningThe 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 sideThe 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 fileThe 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.

any system · upgrade
# move to the newest release (keep the extras you use)
pip install --upgrade "truvelocity-tevv[ui]"
any system · pin
# install exactly one release, for repeatable results across a team
pip install "truvelocity-tevv[ui]==2026.11.18.2"
any system · list releases
# which releases PyPI has
pip index versions truvelocity-tevv
expected (on 2026-11-19)
truvelocity-tevv (2026.11.18.2)
Available versions: 2026.11.18.2, 2026.11.18.1, 2026.11.17.2, 2026.11.17.1
any system · uninstall
# remove the package from this environment
pip uninstall truvelocity-tevv

To 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

SymptomWhat 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.yamlYou 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.org and files.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.1 only and need the one-time key; nothing is uploaded unless you run tv push. Secrets go in .env, which the starter's .gitignore excludes.
  • 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.