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.19.1, 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.

Create a working folder:

Windows PowerShell · 1/7
mkdir truvelocity

Go into it:

Windows PowerShell · 2/7
cd truvelocity

Create the virtual environment with Python 3.12 (use -3.11 for 3.11):

Windows PowerShell · 3/7
py -3.12 -m venv .venv

Activate it: the prompt then starts with (.venv):

Windows PowerShell · 4/7
.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:

Allow scripts in this PowerShell window only:

Windows PowerShell · 4/7 (if blocked)
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 ....

Create a working folder:

Windows cmd · 1/7
mkdir truvelocity

Go into it:

Windows cmd · 2/7
cd truvelocity

Create the virtual environment with Python 3.12 (use -3.11 for 3.11):

Windows cmd · 3/7
py -3.12 -m venv .venv

Activate it: the prompt then starts with (.venv):

Windows cmd · 4/7
.venv\Scripts\activate.bat

Create a working folder:

macOS / Linux · 1/7
mkdir truvelocity

Go into it:

macOS / Linux · 2/7
cd truvelocity

Create the virtual environment (python3 must be 3.11 or later: check with python3 --version):

macOS / Linux · 3/7
python3 -m venv .venv

Activate it: the prompt then starts with (.venv):

macOS / Linux · 4/7
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).

Bring pip up to date inside the environment:

Windows PowerShell · 5/7
python -m pip install --upgrade pip

Install TruVelocity with the UI extra:

Windows PowerShell · 6/7
pip install "truvelocity-tevv[ui]"

Bring pip up to date inside the environment:

Windows cmd · 5/7
python -m pip install --upgrade pip

Install TruVelocity with the UI extra:

Windows cmd · 6/7
pip install "truvelocity-tevv[ui]"

Bring pip up to date inside the environment:

macOS / Linux · 5/7
python -m pip install --upgrade pip

Install TruVelocity with the UI extra (the quotes stop zsh expanding the brackets):

macOS / Linux · 6/7
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.19.1 typing-extensions-4.16.0

The dependency versions may differ on your day; truvelocity-tevv-2026.11.19.1 (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

Print the installed version:

Windows PowerShell · 7/7
tv --version

Print the installed version:

Windows cmd · 7/7
tv --version

Print the installed version:

macOS / Linux · 7/7
tv --version
expected
TruVelocity for AI TEVV 2026.11.19.1

To see every command:

List the commands:

any system · optional
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.19.1 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.2026.11.19.1 and later (recommended)
B. UI prototype with sample dataThe UI with sample agents, read-only. Writes nothing to disk.Every release
C. Offline tour, then the consoleReal runs against a scripted agent (passes, a planted failure, gate, reports), browsed in the console.Every release
Then: practise on a real agenttv practice-project writes a project for an expense desk agent (an LLM agent on Docker Desktop; you add an LLM key) and the step-by-step guide TruVelocity-Onboard-a-New-Agent.html: all six steps to a release decision, then catching planted defects.2026.11.20.2 and later
… without Docker or an LLM keyNo Docker: pip install "harbor-expense-agent[all]", then tv practice-agent runs the agent and the recording proxy on this machine. No LLM key: tv practice-project --scripted writes a .env with DEFAULT_LLM_PROVIDER=SCRIPTED and LLM_SCRIPT=expense_agent.policy:factory, the agent's offline rule-based model (no LLM call, no cost; the planted defects still apply).2026.11.20.2 and later

A. The demo project RECOMMENDED

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

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:

Windows PowerShell · demo project 1/3
tv demo-project

Go into it:

Windows PowerShell · demo project 2/3
cd truvelocity-demo

Start the UI, allow runs from the browser, and open it:

Windows PowerShell · demo project 3/3
tv ui --allow-runs --open

Create the offline demo project:

Windows cmd · demo project 1/3
tv demo-project

Go into it:

Windows cmd · demo project 2/3
cd truvelocity-demo

Start the UI, allow runs from the browser, and open it:

Windows cmd · demo project 3/3
tv ui --allow-runs --open

Create the offline demo project:

macOS / Linux · demo project 1/3
tv demo-project

Go into it:

macOS / Linux · demo project 2/3
cd truvelocity-demo

Start the UI, allow runs from the browser, and open it:

macOS / Linux · demo project 3/3
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

The UI with sample agents (no project needed); opens your browser:

Windows PowerShell · prototype 1/1
tv ui --demo --open

The UI with sample agents (no project needed); opens your browser:

Windows cmd · prototype 1/1
tv ui --demo --open

The UI with sample agents (no project needed); opens your browser:

macOS / Linux · prototype 1/1
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.

The offline tour: runs, a planted failure, compare, scorecard, gate, reports:

Windows PowerShell · tour 1/2
tv demo

Browse the tour's runs and reports in the console:

Windows PowerShell · tour 2/2
tv console --runs-dir tv_demo --open

The offline tour: runs, a planted failure, compare, scorecard, gate, reports:

Windows cmd · tour 1/2
tv demo

Browse the tour's runs and reports in the console:

Windows cmd · tour 2/2
tv console --runs-dir tv_demo --open

The offline tour: runs, a planted failure, compare, scorecard, gate, reports:

macOS / Linux · tour 1/2
tv demo

Browse the tour's runs and reports in the console:

macOS / Linux · tour 2/2
tv console --runs-dir tv_demo --open
expected from tv demo (key lines; paths use / on macOS and Linux)
TruVelocity 2026.11.19.1: 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).

The same UI on port 8790:

any system · another port
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.

A starter project for a task agent, in the folder my-agent:

Windows PowerShell · own agent 1/4
tv new task my-agent

A starter project for a task agent, in the folder my-agent:

Windows cmd · own agent 1/4
tv new task my-agent

A starter project for a task agent, in the folder my-agent:

macOS / Linux · own agent 1/4
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:

Go into the project:

Windows PowerShell · own agent 2/4
cd my-agent

Check the catalog against the schema:

Windows PowerShell · own agent 3/4
tv validate catalog.yaml

Run it against your agent (needs the agent running at TV_AGENT_URL):

Windows PowerShell · own agent 4/4
tv run catalog.yaml --env environment:environment

Go into the project:

Windows cmd · own agent 2/4
cd my-agent

Check the catalog against the schema:

Windows cmd · own agent 3/4
tv validate catalog.yaml

Run it against your agent (needs the agent running at TV_AGENT_URL):

Windows cmd · own agent 4/4
tv run catalog.yaml --env environment:environment

Go into the project:

macOS / Linux · own agent 2/4
cd my-agent

Check the catalog against the schema:

macOS / Linux · own agent 3/4
tv validate catalog.yaml

Run it against your agent (needs the agent running at TV_AGENT_URL):

macOS / Linux · own agent 4/4
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

The wizard over the agents in tv-ui.yaml; the browser may start runs:

any system · UI on your project
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.

Move to the newest release (keep the extras you use):

any system · upgrade
pip install --upgrade "truvelocity-tevv[ui]"

Install exactly one release, for repeatable results across a team:

any system · pin
pip install "truvelocity-tevv[ui]==2026.11.19.1"

Which releases PyPI has:

any system · list releases
pip index versions truvelocity-tevv
expected (on 2026-11-19)
truvelocity-tevv (2026.11.19.1)
Available versions: 2026.11.19.1, 2026.11.18.2, 2026.11.18.1, 2026.11.17.2, 2026.11.17.1

Remove the package from this environment:

any system · uninstall
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.