Glossary¶
Troupe's own words, one definition each, in alphabetical order. A page that uses one of them for the first time links here.
Agent¶
What talks to the model: a markdown file of instructions, the tools it may use and,
optionally, which model. A session starts with one, build (reads, edits and runs
commands) unless you pick another — plan reads and proposes and never writes,
orchestrate hands a change to subagents and runs workflows, and others ship too — and
it may hand parts of its task to subagents. Your own configuration, a workspace or a
bundle can add more.
Approval¶
The question a session asks before a tool that changes something runs: writing or editing a file, running a command, and whatever else a configuration says asks. The answers are allow, deny, or allow that tool for the rest of the session. Anyone attached with control can answer and the first answer wins; with nobody attached, the call waits, or is denied where the configuration says so.
Branch¶
A session opened from another one in the terminal UI (/build, /worktree), with a window
of its own, often in its own worktree. Branches run side by side, and a window that needs
you says so.
Budget¶
The limits after which a session stops and asks. On every agent: model calls, input tokens,
output tokens and time, set in config.yaml. On a plane, money as well: per team, per
person and for the platform. Reaching one asks, or stops when nobody can be asked; it never
carries on silently.
Bundle¶
The agents, skills and MCP servers a profile's sessions carry, published on the plane in versions. A session keeps the version that was current when it started.
Client¶
Anything that attaches to sessions over PROTOCOL.md: the terminal UI
(troupe), the desktop app, the web app a plane serves at /app, or a program of yours.
None of them can do anything the protocol does not offer every client.
Console¶
The administrative app, at /console: fleet, identity, teams, budgets, profiles, policy,
bundles, triggers, principals and the audit trail. Each button calls a method that the admin
API offers as well, over JSON-RPC and MCP. It is the one administrative surface: the plane
has no pages of its own for administrators, and break-glass is a way into the console.
Daemon¶
troupe-daemon, the harness on your machine. It holds the sessions that run here, and
every client on the machine attaches to it. troupe runs one inside itself while it is
open when none is running on its own.
Gateway¶
A proxy in front of model providers, such as LiteLLM or vLLM, reached with one URL and one
key. Troupe talks to one as a provider of the API it speaks, usually openai, with a
base_url, and records the cost a gateway reports for each call.
Goal and loop¶
A goal is what a session is working towards (/goal <text> in the terminal UI); the agent
sees it on every turn until it is cleared. /loop lets the session work towards it on its
own, for a number of turns, until the agent says the goal is met or a limit is reached.
Harness¶
The code that runs agents: the agent loop, the tools and the log. The same harness runs in the daemon on your machine and on a worker pod.
Log¶
A session's append-only, hash-chained record of everything that happened in it: each input, model call, tool run and approval, and what the calls cost. The log is the session: every view of it, every restart and every audit is read back from the log.
MCP server¶
A program that gives an agent more tools over the Model Context Protocol: a database, a
browser, an issue tracker. Yours live in mcp.json, in the shape other agent tools use; a
workspace's and a bundle's are added to them.
Operator¶
The Kubernetes controller that turns a profile into a namespace of worker pods, and the policy into what those pods may do. It holds the cluster privileges and has no public endpoint.
Plane¶
The server your team signs in to. It knows who you are, which teams you are in, which profiles they may use, where each remote session runs and what it cost, and never what a session said.
Policy¶
The platform's rules for every profile, as a TroupePolicy: which images, which hosts a
worker may reach, which ceilings apply. The operator refuses a profile that breaks it, and
so does the cluster on Kubernetes 1.30 or later.
Principal¶
Whoever acts: a person, signed in through your identity provider, or a service principal. Every event in a log names the principal behind it.
Profile¶
A kind of worker, written as a WorkerProfile: an image, a model, tools, storage and which
bundle channel it follows. A remote session runs on one, and a team may use the profiles
granted to it; with only one, you never have to name it.
Project brief¶
What earlier agents found out about a repository, kept as facts in
.troupe/memory/facts.jsonl, each with the files it rests on and who checked it: a fact
whose file has changed since is marked "may no longer be true". Every agent's prompt carries
the commands and conventions; the rest it asks for with recall. .troupe/memory.md is a
view of the facts for a person to read, and an edit to it is read back. Agents add facts
with remember; a librarian session surveys the repository and keeps them current.
Provider¶
Where the model is: Anthropic, OpenAI, Azure OpenAI, Gemini, OpenRouter, Ollama, or a gateway that speaks Anthropic's or OpenAI's API (provider types). You bring the key; Troupe calls it and counts what each call used.
Service principal¶
A credential a team owns for work nobody starts by hand, named svc:<team>/<name>. It signs
in as a person does and can hold no admin role.
Session¶
One agent, and the agents it delegates to, working in one workspace, with its log. It lives
in the daemon or on a worker pod, not in the window you look at it through, and it is
active, dormant (stopped with its log kept, woken when opened), read_only or erased,
and on a plane pending too (waiting for a worker while its profile grows);
a session being erased is erasure_pending until its key is destroyed.
Skill¶
Instructions for one kind of job, in a directory with a SKILL.md, which an agent reads
when the job comes up. Yours, a workspace's and a bundle's, in the shape other agent tools
use.
Team¶
A group from your identity provider that an administrator has enabled. It carries a budget, how long its sessions are kept and the profiles it may use; who is in it is the identity provider's business, not Troupe's.
Trigger¶
A job that starts a session with no person at the keyboard, on a schedule or fired from outside, as a service principal and on a budget of its own. Its sessions are flagged for review until somebody has looked.
Worker¶
A pod, or a machine the plane provisions, that runs the harness for the plane. A profile has as many as its sessions need, and none while it is idle; each holds many sessions, and a client reaches it directly over a WebSocket with a short-lived token.
Workspace¶
The directory a session works in, usually a repository's checkout. Its .troupe/ directory
holds what the repository wants: settings, agents, skills, MCP servers, workflows and the
project brief.
Worktree¶
A git worktree Troupe makes so a branch works on its own copy of the checkout, merged or discarded when it is done.