Skip to content

troupe, the terminal client

troupe is the terminal client of the Troupe harness: an Elixir TUI, one self-contained executable per platform built with Burrito, that speaks PROTOCOL.md to the troupe daemon on this machine (or the same daemon started inside itself) and to a plane's worker pods.

Installing it, using it, its exit codes and its remote sessions are on the terminal client; its screen on the terminal client's screen, and every command line and command on the command reference.

Development

The toolchain is pinned in .tool-versions / mise.toml: Erlang 28.5, Elixir 1.20.4, Zig 0.16.0 (Burrito 1.6 requires exactly that Zig).

mix deps.get              # the harness apps are path dependencies on ../../apps
mix check                 # compile --warnings-as-errors, format, credo --strict, xref, the generated files' checks, test
scripts/dev [args]        # run the CLI/TUI from source without a build (dev loop)
scripts/build-local       # Burrito binary for this host, installed as ~/.local/bin/troupe
TROUPE_PROVIDER=fake TROUPE_FAKE_SCRIPT="$PWD/fixtures/fake_scripts/smoke.json" \
  troupe run build smoke --headless --auto-approve

The harness (troupe_core, troupe_gateway, troupe_protocol) is a path dependency on ../../apps/, the umbrella this project sits in, at the same commit: there is no pin to bump, and a change to the harness is made there, with PROTOCOL.md and a decision in docs/decisions/, in the same pull request as the TUI change that needs it. A package both this project and the umbrella lock must be at one version in both mix.lock files; elixir scripts/locks-agree.exs at the repository root checks the ones they share, and CI runs it. The version is the root VERSION. troupe_core's compile cross-compiles the reaper helper for the host, and TROUPE_REAPER_TARGETS=all builds every target (the release does this). Every OS process a session starts runs under reaper, which kills the whole process tree when its owner dies. TROUPE_PROVIDER=fake and TROUPE_FAKE_SCRIPT give a deterministic model; so do provider: fake and fake_script: in a workspace's .troupe/config.yaml, once the workspace is trusted, which is how the test suite does it. mix troupe.remote.smoke runs login, list, attach and one input against a real deployment when TROUPE_REMOTE_URL is set, and skips itself otherwise.

The harness is the harness and its clients; this client's supervision tree and its remote client are §7 there; and its decisions are every deviation from the original specification.

Out of scope (for now)

Offering this machine's built-in tools (its files, its shell) to a remote session (a person's own signed-in MCP servers are offered), a GUI for the remote side (that is clients/gui, beside this directory), a Web UI, multi-node distribution, a resident assistant or free-text routing at the dispatcher, auto-commit or undo in the user's checkout, updating itself unasked, the operating systems' own code signing and notarisation (every release is signed with the release key, which troupe update checks; code-signing.md), and native Windows ARM builds.