Skip to content

Quick start

A laptop, ten minutes and a key for a model. By the end of this page you have installed Troupe, run a session, seen what it spent, capped what the next one may spend, and know what a plane would add. Troupe's own words are in the glossary.

The blocks marked for it in this page's source run in CI, on Linux and on Windows, against the latest release: every night, and on every change to this page (quick-start.yml). What CI cannot run is at the end.

1. Install

On Linux or macOS:

curl -fsSLO https://github.com/it-minds/troupe/releases/latest/download/install.sh
sh install.sh --tui

On Windows, in PowerShell:

irm https://github.com/it-minds/troupe/releases/latest/download/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Tui

That installs the latest release's daemon, troupe-daemon, and its terminal client, troupe, for your user alone: in ~/.local/bin, or %LOCALAPPDATA%\Programs\troupe on Windows. Every download is checked against the release's SHA256SUMS first, and against the release's signature where minisign is installed; in a terminal the script shows its plan and asks before it changes anything; read it before you run it if you like. --gui (-Gui) adds the desktop app, and --vscode (-VSCode) the VS Code extension where VS Code is.

The programs carry no Apple or Microsoft signature yet. The installers download with curl and Invoke-WebRequest, which Gatekeeper and SmartScreen rarely stop; for a download made in a browser, the first time:

  • macOS refuses to open it: System Settings โ†’ Privacy & Security, then Open Anyway beside the message about Troupe, or xattr -d com.apple.quarantine ~/.local/bin/troupe.
  • Windows says "Windows protected your PC": More info, then Run anyway.

What makes that safe is the release's own signature, which troupe update and the desktop app check before every update (security).

Open a new terminal, so that the PATH the installer set is read, and check:

troupe --version

2. Bring your own key

Troupe runs no model of its own. It calls the provider you name, with your key, and charges you nothing. The shortest way in is a key in the environment:

export ANTHROPIC_API_KEY=sk-ant-...     # PowerShell: $env:ANTHROPIC_API_KEY = "sk-ant-..."
troupe config
troupe doctor

troupe config says which provider and model a session will use. With no key anywhere it asks instead, for Anthropic, OpenAI, a gateway such as LiteLLM, or your organisation's plane, and writes the answer to config.yaml; troupe setup asks the same on screens. troupe doctor checks the setup one line at a time, the key by asking the provider for its list of models, which costs nothing. What each checks, and troupe doctor --bench, an offline run of the harness itself, are in the first run; every setting, and which file wins, in configuration.md.

3. A first session

Make a directory with something wrong in it, and ask about it:

mkdir hello-troupe && cd hello-troupe
printf 'def add(a, b):\n    return a - b\n' > add.py
troupe run plan "Read add.py and say in one sentence what is wrong with it." --headless
mkdir hello-troupe; cd hello-troupe
Set-Content add.py "def add(a, b):`n    return a - b"
troupe run plan "Read add.py and say in one sentence what is wrong with it." --headless

troupe run starts a session in this directory, its workspace, and prints what the agent does, a line for each event, until it comes to rest. plan is the agent that reads and never writes, so nothing in this run needs you; the exit code says how it ended (the codes).

Now have it fixed, in the terminal UI:

troupe

Type fix add.py and press Enter: the build agent takes it, in a window of its own. Reading is automatic; editing a file and running a command are not. The agent stops at each and its window asks for an approval: press the window's number (or Enter) to open it, then y allows it, n denies it, a allows that tool for the rest of the session. Ctrl-D quits.

The terminal UI: the agent has read add.py, found the subtraction, and waits for approval of its one-line edit

With no daemon running on its own, troupe runs one inside itself, so the session stopped when you quit. Its log is kept, and troupe resume opens the session where it was. To keep sessions working with no window open, run the daemon on its own, troupe daemon run in a terminal you leave open, troupe daemon login on to have it start every time you log in, or use the desktop app, which starts it; every client on the machine then sees the same sessions.

4. What it cost

Every model call's tokens are in the session's log. The terminal UI shows each window's tokens sent and received (โ†‘5.2k โ†“184), and the desktop app shows each session's cost. The log is JSON, a line an event, under ~/.local/state/troupe/sessions/ (%LOCALAPPDATA%\troupe\sessions\ on Windows), and it answers the question by itself. With jq, for every session on this machine, which after this page is three (the plan run, the terminal UI's session, and the window fix add.py opened, which is a session of its own):

cat ~/.local/state/troupe/sessions/*/*/events.jsonl | jq -s '
  [.[] | select(.type == "llm_response") | .data] | {
    model_calls: length,
    input_tokens: (map(.usage.input_tokens // 0) | add),
    output_tokens: (map(.usage.output_tokens // 0) | add),
    cost_usd: ([.[].gateway.cost_micros | numbers]
               | if length == 0 then "not priced" else add / 1000000 end)
  }'

A task this small is a couple of model calls and some thousands of input tokens, most of them the agent's instructions and tool definitions. The nightly CI runs a task like it against a real model and lists what each run used (developer/ci.md); a recent one took two calls, about 7,500 input tokens and 50 output tokens. Your model and your task will differ. At $3 per million input tokens and $15 per million output tokens, figures for the example and not anybody's price list, that run cost about two cents.

Troupe keeps no price table of its own. A call's cost is what your gateway reports, as LiteLLM does, or what you tell it the model costs; a provider's own endpoint reports tokens only, so cost_usd above says not priced until you write your price into config.yaml:

models:
  prices:
    claude-sonnet-5: {input: 3, output: 15}   # dollars per million tokens: your model's price, by the name you use for it

5. Cap the next one

Every agent has four limits, and the defaults are generous: 40 model calls, 2,000,000 input tokens, 400,000 output tokens and 30 minutes. At the example prices that is up to $12 of tokens. The agents a session delegates to draw on its tokens and its time, so those two limits hold for the whole session; only the model calls are counted per agent. A first week needs less:

mkdir -p ~/.config/troupe
cat >> ~/.config/troupe/config.yaml <<'EOF'
max_turns: 10
max_input_tokens: 200000
max_output_tokens: 20000
EOF
troupe config --explain max_input_tokens
New-Item -ItemType Directory -Force "$env:APPDATA\troupe" | Out-Null
Add-Content "$env:APPDATA\troupe\config.yaml" "max_turns: 10`nmax_input_tokens: 200000`nmax_output_tokens: 20000"
troupe config --explain max_input_tokens

--explain shows the value in force and which file set it. Now a session stops after 10 model calls, 200,000 input tokens or 20,000 output tokens: at most $0.90 at the example prices. At 80% of any limit the agent is told. At the limit the terminal UI and the desktop app ask you how much more, for this run, this session or this workspace, or whether to stop; a headless run has nobody to ask, and stops. Nothing carries on silently. troupe --full-send lifts the limits for one session, and even then a tool that fails ten times in a row stops the turn and asks. Every budget key is in configuration.md.

What the limits do not count, so that you are not surprised: prompt tokens the provider serves from its cache, which it bills at a fraction of the input price; a branch you open in the terminal UI, which is a session with limits of its own; and, the first time you open troupe in a git repository, a librarian session that writes the project brief (memory_auto_refresh: false turns that off).

6. What a plane adds

Everything so far ran on your machine and needed nothing else. A plane is the server a team runs on its Kubernetes cluster, and it adds:

  • Sign-in and teams from your identity provider. Nobody has a Troupe password, and nobody edits membership in Troupe.
  • Money budgets per team, per person and for the platform, reserved when a session starts and charged with what its calls cost.
  • Sessions on worker pods, which keep working with every laptop closed and which a colleague can open with you.
  • Profiles, bundles and triggers: what a team's sessions run on and carry, and work that starts on a schedule.
  • An audit trail of every administrative change, with its diff, which can say whether it has been altered.
  • A console at /console for all of it.

The admin console's teams page: example teams, the identity-provider groups they draw their members from, and the profiles each may run

With a plane's address from whoever runs it:

troupe login https://troupe.example.com
troupe --remote

troupe login signs you in with a code you type in your browser, where you already sign in. The desktop app lists this machine's sessions and the plane's in one list. Whether you need a plane at all: why-troupe.md. Running one: admin/installing.md.

troupe update installs a newer release over these, once its signature checks against the release key (updating), and the desktop app updates itself. To remove Troupe again: sh install.sh --uninstall, or -Uninstall on Windows; add --purge (-Purge) to remove its settings and session logs too.

What CI does not run

The job runs every marked block above, in order, as one script: the sh ones on Ubuntu and the powershell ones in PowerShell on Windows, from the installers a reader downloads. It cannot run:

  • your key. It sets TROUPE_PROVIDER=fake instead, a scripted model that answers from a file, so every command runs for real and only the model's answer is canned.
  • the terminal UI. troupe needs a person at a terminal; the TUI's own suite draws it headless.
  • macOS. The Linux job runs the same install.sh; the macOS builds are smoke-tested by native.yml nightly and at every release.
  • a plane. Section 6 is a pointer, not a step.