Skip to content

Setting up and checking a machine

What the first run asks, what troupe config does on a machine with no settings, how troupe doctor checks the setup, and signing in to a plane. The files it writes, and every key in them, are on configuration.

troupe setup

troupe setup sets up a model, one question to a screen: where the work runs, the provider (a key in the environment, an opencode setup or a working config.yaml is offered first), the key, the models with their context and price, a first project and what the agent may do there without asking, and whether the daemon starts when you log in. A summary comes last, and nothing is written before it: Enter writes it and opens the first session in that project, Esc leaves with nothing written, Shift-Tab goes back a step. Run it again whenever you like. Without a terminal (standard input or output redirected) it says which and prints the ways on instead.

The settings are one file, config.yaml in ~/.config/troupe/ (%APPDATA%\troupe\ on Windows, with every other file of your own; where your files are), and troupe config shows what is in force. The cookbook has a complete file for each provider and more; the smallest is Anthropic's, the key read from the environment. Your organisation may set defaults below it and limits above it; troupe config --explain says which (configuration). troupe config validate checks that file after you edit it by hand.

With no settings and no key, plain troupe opens troupe setup's screen before the session. troupe config, on a machine with no config.yaml, offers in a terminal to copy an opencode setup's providers (keys as opencode has them written), and otherwise three choices: set up a provider here, line by line (Anthropic first, then OpenAI or a gateway: provider, URL, key and a model from what the provider lists; Enter at every question is Anthropic with api_key: "{env:ANTHROPIC_API_KEY}"); take your organisation's settings from a plane (troupe login, then troupe config pull); or not now. Without a terminal it prints the choices and asks nothing. A config.yaml through which no model can be asked gets the report and then the same choices, and the installers end with the same check. Whatever finds no key says so with one next step, troupe config: the report's last line, a headless run's model error, the first turn in the TUI. A first run finished in the desktop app is recorded by the daemon, and plain troupe asks nothing then.

In the desktop app

The desktop app asks the same questions on its first run, as screens, then opens a first session with a suggested prompt. It writes the same config.yaml, and once it is done the terminal client does not ask again. Setup in the app's rail runs it again at any time, and a session whose key the provider refuses offers it too. Without either, the app's This computer screen, under Models, sets up the same file, or you write it yourself.

troupe doctor

troupe doctor checks the setup, one line each: the config files load, the default model's provider has a key, the key is accepted (a real request, the provider's model list), the model answers (the smallest request a turn makes, one token, through the same code a session uses, with the sentence a turn would end with when nothing comes), what the requests tell the provider about Troupe (identify), where the key is kept, that the helper every command runs under starts, whether a daemon is running, troupe-daemon and troupe on the PATH, every plane you are signed in to, and whether local_only is on. A line that says FAIL makes it exit 1; warn does not. troupe-daemon doctor prints the same lines. troupe doctor --bench then says whether a session gets through the harness on this machine: a turn of thirty tool calls, a tool output too long to send whole, a compaction, a cancel, a replay of the session's log, thinking made before the prompt changed, Claude Code's, opencode's, Cursor's and Copilot's files onboarded, and a remembered command whose file changed since, eleven scenarios run in troupe itself against a scripted model, so in a few seconds and with no provider, key or network, a line each saying it passed or what did not hold (--json prints it as one object). troupe bench --live goes further: four small tasks against your model, under a cap it prints and asks about first, saying whether they got done and what each cost (what a task costs).

Signing in to a plane

troupe login <plane URL> signs you in with a code you type in your browser; you sign in where you always do, and Troupe never has a password of its own. That sign-in is the machine's: the installer's troupe config runs it, the desktop app opens signed in with it and starts at that plane, and the daemon is linked to you at it there and then, so a private session and its artifacts are yours from either client. A sign-in made in the desktop app is troupe's the same way, and signing out in one is signing out in both.