Tutorial · step 0

Install TeamRunner

Two commands: one installs uv, the other installs TeamRunner with it. You don’t need Python first. About two minutes, and it costs nothing.

What is uv? One small program that does the whole Python job for you: it fetches the right version of Python, installs tools like TeamRunner each in their own space so they never clash, keeps them up to date, and runs them. It replaces installing Python, pip and virtual environments by hand.

It is free and open source, made by Astral. Nothing it installs touches the rest of your computer’s Python.

Your system

You type these in a terminal. Paste a line and press Return.

Open Terminal (press ⌘ Space, type “Terminal”, press Return) and install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Close Terminal and open it again, so it finds uv. Then install TeamRunner:
uv tool install teamrunner
Open TeamRunner in your browser:
teamrunner ui

Open PowerShell from the Start menu and install uv:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

This is the Windows version of the same installer; irm is PowerShell’s download command, like curl.
Close PowerShell and open it again, so it finds uv. Then install TeamRunner:
uv tool install teamrunner
Open TeamRunner in your browser:
teamrunner ui

In a terminal, install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

No curl? Use wget -qO- https://astral.sh/uv/install.sh | sh.
Open a new terminal, so it finds uv. Then install TeamRunner:
uv tool install teamrunner
Open TeamRunner in your browser:
teamrunner ui

Just looking? uvx teamrunner ui runs TeamRunner once without installing it.

Already have Python? Use pip

With Python 3.10 or later, one line does it. Use a virtual environment if you keep one.

pip install teamrunner

Then teamrunner ui, as above.

Check that it works, for free

A rehearsal runs a whole team with no model, so it needs no key and costs nothing.

In your browser, on the page teamrunner ui opened: choose New team, call it hello and start from round_robin. Then Run… and Rehearse team.
Or in the terminal:
teamrunner new hello --from round_robin

teamrunner run hello --rehearse

If it ends with completed, you are set.

what you seefree

rehearsal · no model is called; the words are placeholders and the answers random
for                                       0.0s   $0.0000
    “[rehearsal] placeholder words, turn 1.”
against                                   0.0s   $0.0000
    “[rehearsal] placeholder words, turn 2.”
judge          winner = for               0.0s   $0.0000
    “[rehearsal] placeholder words, turn 3.”

completed · 3 turns · 0.0s · ≈ $0.0000

TeamRunner's page in a browser: the hello team's files on the left, an agent's instructions open in the editor — Your team’s files, open in your browser, on your own computer.

Keep it up to date, or remove it

Update: uv tool upgrade teamrunner (with pip: pip install -U teamrunner)
Remove: uv tool uninstall teamrunner. Your teams are ordinary folders and stay where they are.

If something goes wrong

uv or teamrunner: command not found. Close the terminal and open a new one. If it still isn’t found, run uv tool update-shell, then open a new terminal again.
Windows says scripts are disabled. Use the PowerShell line exactly as shown; -ExecutionPolicy ByPass applies to that one command only.
Anything else: open an issue or write to hello@teamrunner.ai, with what you typed and what it printed.

← All steps Step 1: Rehearse a team →