Skip to content

Troupe for users

Troupe runs a coding agent for you. You give it a task in a directory; it reads, edits, runs commands and reports back. The work lives in a session: a process on one of your team's worker pods, or in the daemon on your own machine, and the window you look at it through is only a window. Close it and the session carries on; open it from another machine and you see the same transcript; two people can open the same session at once.

First run

  1. Install troupe and troupe-daemon with the latest release's install.sh or install.ps1, saying yes to the TUI (quick start).
  2. troupe setup sets up a model, one question to a screen, and writes one file, config.yaml; troupe config shows what is in force, and the desktop app asks the same on its first run (setting up).
  3. troupe in a project directory opens a session; troupe run "a task" --headless does one task and exits.
  4. Give it a task. Writing or editing a file and running a shell command ask you first (approvals), and when the turn ends it says what it cost (what a call costs).
  5. When something does not work, troupe doctor checks the setup one line at a time (troupe doctor); for everything else, the pages below.

Ways in

On your own machine every way in is a client of one daemon, troupe-daemon, which runs your sessions and outlives the windows you look at them through. Whichever client needs it first starts it (the terminal client runs one inside itself when none is running), and it stops on its own a while after the last client leaves, or never once troupe daemon login on has it start at login (troupe-daemon, start at login):

flowchart LR
  subgraph machine["Your machine"]
    tui["troupe"]
    app["the desktop app"]
    own["your own program"]
    daemon["troupe-daemon<br/>one per user"]
    sessions["your sessions<br/>a process tree each"]
    dir["the directory<br/>you gave it"]
    state["the state directory<br/>each session's log"]
  end
  model["the model provider"]
  plane["your team's plane<br/>only when signed in"]
  store[("object storage")]

  tui -- "a Unix socket or loopback TCP,<br/>and a loopback WebSocket" --> daemon
  app -- "a loopback WebSocket" --> daemon
  own -- "any of the three" --> daemon
  daemon --> sessions
  sessions -- "reads, edits, commands" --> dir
  sessions -- "one events.jsonl each" --> state
  sessions -- "HTTPS, your key" --> model
  daemon -. "a private session's row,<br/>and URLs to store it" .-> plane
  daemon -. "its sealed copy" .-> store
Way in What it is Its documentation
troupe the terminal UI, on the daemon on your machine; troupe --remote for your team's plane clients/tui
VS Code Troupe: Open opens troupe in a terminal tab beside your files, at the folder you are working in; the Troupe side bar shows that folder's settings vscode.md
The desktop app, or the GUI at your plane's /app the graphical client: sessions on your machine and on the plane in one list, approvals from an inbox. Use this computer only on the sign-in screen skips signing in and never contacts a plane. In a browser, troupe-daemon open connects the GUI to your machine clients/gui; installing the unsigned desktop builds: install.md
Your own program anything that speaks PROTOCOL.md to a daemon or a pod the protocol
Another agent a profile called through the A2A facade a2a.md

The pages

The glossary defines each of Troupe's words: a plane, a team, a profile, a bundle, a trigger and the rest. Each page below explains one thing, and the others link to it.

What Troupe never does

  • It never reads your session on the plane. The plane holds who, which profile, which state and what it cost. The transcript lives in the pod's log and in storage encrypted under keys the plane cannot use. No administrative method returns what a session said.
  • It never writes where you cannot see. Every file change goes through a tool that is either an approval prompt or a durable event in the log, and nothing Troupe keeps for itself lands in your working directory.
  • It never approves its own commands unattended. An unattended session waits for a person or is configured to deny. --auto-approve is a choice a client makes for itself, and the log records that client as the approver.
  • It never uses your machine unasked. Offering your own tool server to a session takes a deliberate confirmation, and everyone on the session sees it.
  • It never merges. A session pushes only its own troupe/* branch, never with force, and opens a pull request only as a draft; a person reviews and merges it. The agent's shell never holds a GitHub token: the pod's own tools do the pushing.

Everything it does unasked, and what it never does, in one place for a reviewer: security. How it works underneath: ARCHITECTURE.md. Running the platform: admin/.