The console¶
The console is where platform admins and team admins set Troupe up and watch it run, and
where anybody the plane knows steers the laptop sessions offered to them from a browser. It
is an app of its own (#56), beside the GUI rather than part of it, at /console on the
plane's host, and it is the one administrative surface the plane has: the plane serves no
pages of its own for administrators, and /admin, where it once did, sends the browser
here. This page says where the console is and what it does.
Where it is¶
At /console on the plane's own host: https://troupe.example.com/console. The chart
serves it from the GUI's image, with an Ingress of its own (console.enabled, on by
default, and console.basePath, configuration.md), so it is there
whether or not the GUI is, and turning it off leaves the GUI alone. The plane's index at /
links to it, and /admin and every page address under it redirect to it
(TROUPE_CONSOLE_URL, which the chart sets from console.basePath). A plane deployed with
the console turned off is administered with troupe admin, over /rpc or with the admin
MCP tools at /mcp, which answer the same methods to the same roles; its /admin is a
short page saying so.
It needs no CORS entry and no worker origin: it is on the plane's origin and opens no
socket to a worker, only the plane's own (/v1/relay/watch for the list of what is offered
to the person, /v1/relay/session to steer one). It does need one thing at the identity provider: its address,
https://<plane host>/console, registered as a single-page application redirect URI on
the application the plane signs in with, as the GUI's /app is
(integrations.md).
Signing in¶
With the plane's own sign-in: the identity provider's page and back, then the plane's
token, as every client gets. Nothing in that token says "administrator". The plane works
out on every call what the person administers, from the provider group named for platform
admins and the teams a platform admin named them on (roles-and-permissions.md),
so a role taken away holds at the next click. Somebody who administers nothing signs in
too, as a member, to the four areas that hold something of theirs (Artifacts,
Memory, Sessions and Client versions), each showing them their own; an
administrative role adds the rest of the map below. An address of an area the role lacks
opens where the role starts (Sessions for a member, the Overview for an administrator), says
in one line that the page is for administrators, and the address becomes that place's. An
address kept from before a page moved opens where it is now and becomes its address:
#/mine is Sessions' Mine, #/mine/remote/<id> and #/mine/invited/<id> the session
under it, and #/published Artifacts.
A link to any screen or team tab (/console/#/teams/core/limits) works signed out too: the
console lands there once the provider sends the browser back, not on its first screen.
The sign-in lasts as long as the browser tab: a reload keeps it, and a new tab signs in again, which against a provider you are already signed in to is a moment's redirect.
When the provider cannot let you in: break glass¶
The console signs in through the identity provider, so on the day the provider cannot let
anybody in (a registration saved wrong, a group nobody carries, a tenant outage, a fresh
installation with no admin group yet) the way in is the break-glass token. Break glass
on the sign-in screen takes it, and the plane answers a plane token for the break-glass
subject (POST /auth/breakglass,
roles-and-permissions.md §4, which says what it
may do and for how long). The steps that put the wrong value right are
locked out of the console.
The sign-in screen offers Break glass only on a plane whose door is configured, which
/.well-known/troupe says (breakglass).
What it does¶
The map is five groups: Oversee, what the plane holds, every artifact and every memory document (a person's own among them for a platform admin), then the brief's four, Watch, Configure, Operate and Govern. It is the administrator's whole view: what is your own is a filter on the page where everybody's is, Mine on Artifacts and on Sessions, Your own on Memory, Your clients on Client versions. A team admin is shown only what the plane answers a team admin. On a narrow screen the map folds behind a Menu button.
The console names what an administrator runs as they run it: a pod, a worker, an image, a channel, a drain, a node, and the cluster where a page is about its resources. What a person has another word for it says in that word, as the apps do: a profile (never a worker profile), a session that is asleep or started (never dormant or activated), and the platform or the plane where it means where sessions run (Decision 993).
| Area | What it does |
|---|---|
| Artifacts | The first area; every role has it. The pages, documents and files people and agents published (artifacts, Decision 948). An administrator's opens on Every artifact (admin.artifacts.list, Decision 953): a platform admin's is every one, people's private ones included, and a team admin's the artifacts of the teams they administer (team:<name>) and those the teams own; a row is its title, kind, who it is for, owner, the team that owns it if one does, team, versions and what it stores, never its content, and Take down (admin.artifact.takedown) deletes every version and stops every link without asking the owner, typed by its id, audited as artifact.delete with by: takedown. A row's title opens the artifact's page; one that is not yours is read as its administrator (admin.artifact.get): its versions, who it is shared with, its links with who used each, and its comments, a private one's too, and each read is a row in the audit, artifact.read (Decision 1049); another person's private one does not open on the artifacts host, which stays its owner's and their links' holders'. Then, for everybody, the tabs: Mine, your own (private ones among them), those a link shared with you, the organisation's, your teams' (team:<name>, the team named on each card) and each profile you are granted, as the plane's scope on each says (Decision 953); a card is the title and the kind, never the page. The artifacts host's policy lets a page load only its own files, and the plane reads each version's pages, stylesheets and scripts for what that policy will block as they are published, so its publisher is told and its page says how many (Decision 1048). An artifact's page lists its versions, who published each and its note, the session it came from, and Open, which opens it, or the version the switcher names, on the artifacts host in a new tab (Decision 950). Its owner, and whoever holds an edit link, edits a page's or a document's text with the artifacts host's own preview framed beside it and saves it as the next version, or rolls back to an old one; the owner pins the version its address serves, makes and revokes links (view or edit, honouring the plane's sign-in, each listing who used it) and deletes it; a platform admin takes down any, and a team's admin their team's. An artifact a team owns (one published to the team, unless its publisher kept it, or given to the team with Transfer; the card and the page name the team) is every member's and team admin's to do all of that with as an owner, and a team admin or a platform admin may take it back for themselves (Decision 964). Whether there are artifacts at all, who may publish to the whole organisation, and whether an owner may make a public link (artifacts_public_links, off by default: view only, expiring within 90 days, and off again for every one when it is turned off) are settings under Policy and settings; each team's storage quota is on its Limits tab, and what its artifacts hold is on Budgets. How long they are kept is two more settings there, both off (0) by default: artifacts_keep_versions_days removes a version older than the newest that many days after it was published, never the newest or a pinned one, and artifacts_keep_unopened_days removes an artifact nobody has opened, republished or changed for that many days, whole; an hourly pass removes what has run out, each removal in the audit trail as by: retention (Decision 1019), the cards, Every artifact and an artifact's page say when each goes. They are the organisation's alone: a team cannot change them yet. |
| Memory | Every memory document the plane holds that your role answers for. The organisation's memory and each team's (#55, Decision 922): what every agent in that scope starts from, reaching each session as instructions from the organisation before the person's own and the repository's, which no agent can change. An agent may propose an entry for its team's or the organisation's (remember with level team or organisation): it waits under Waiting for review at the top of the page, with where it would go, the agent, its session and the person, and is in no session's memory until somebody who may change that level accepts it, previewed as a save and written as the next version with the agent and session as who wrote the line, or declines it with a sentence the session is told; the Overview counts them, and the setting Agents may propose memory on Policy and settings turns proposals off (Decision 1004), and the field of that name on a worker profile turns them off for its sessions alone (Decision 1012). Each save is a new version with who saved it, shown line by line before it is made. The organisation's is a platform admin's to change, a team's its team admins'; a worker profile's is edited on the profile's page, below the memory it has from the profiles it extends, which its sessions read first (Decision 929). A save reaches the sessions already running in its scope at their next turn, and people's own machines within five minutes; a profile deleted takes its memory with it. Who reads it, under each document, lists every running session it reaches that has had a turn, with the version its last turn ran under and when, and says how many are behind; Nudge tells a pod's session again (a session on a person's machine hears at its daemon's next poll, within five minutes, and the nudge says so), though a pod's session also asks as each turn begins. An open version can be set Beside the one in force, two columns with the changed lines marked, and restored (Restore version): its text saved as the next version, previewed first and audited as rolled back to it (Decision 947). Who wrote each line sets the version each line came in and who saved it in a column beside the line (Decision 951). Each ## Topic section of a document is an entry, and on a topic a closer level also has (a team's over the organisation's, a profile's over a team's, a person's own over all of them) a session reads only the closer one's, which says what it replaces; so a section here that a team or a person wrote their own of is not in their sessions' prompt; a rule nobody may override belongs under a topic nobody else uses, or in a profile's per-tool rules. Its entries lists the version shown that way, read only, each with who last changed it and in how many sessions it was used (Decision 957). The document stays what is edited, here and through admin.memory.put, which also takes entries; a platform admin can change the organisation's and a team admin their team's from their own app too, the desktop app's Memory or the terminal's /memory, which send the same methods through their daemon; this document editor stays the administrators' other way, and the only one for a worker profile's. Sessions marks a running session whose last turn read an older version than the one in force. Profiles' lists each profile's document, with its version, size and when it changed, linked to the profile's page. For a platform admin, People's own lists everybody who keeps memory of their own, the level every session of theirs reads after the others (Decision 943), with its version, size and who saved it when, never its text (admin.memory.people); Read opens one on a page of its own, read only, any version of it with what it changed (admin.memory.person), and every read is a row in the audit, memory.read on user/<subject> with the version read, so who read whose is on Audit (Decision 1049). No administrator changes a person's own: it is theirs and their agents', and it goes when the person is removed. A team admin reads nobody's. Last, Your own: your memory, to change with a preview, which is all a member's Memory has beside their organisation's and teams' to read. The page's methods: admin.memory.list, admin.memory.people and admin.memory.person (the documents you may read), admin.memory.get (a version with its history, readers, lines and entries), admin.memory.preview and admin.memory.put (a save), admin.memory.rollback (Restore version), admin.memory.nudge, and for what waits for review admin.memory.proposals, admin.memory.accept and admin.memory.decline. |
| Overview | Where the console opens. Needs attention first, worst first, each with where it is fixed: a pod that is broken, has never reported or is draining, a profile short of pods, a team at or near its ceiling, unattended runs nobody has looked at. Then each profile's fleet (pods, capacity, in use) and each team's spend against its budget. Scoped to what you administer. A platform admin's also has Key manager: each grant the plane's OpenBao role needs, checked look-only, and for one it lacks the sentence, under Needs attention, and the bao lines an OpenBao administrator runs (openbao.md). |
| Sessions | Every session you may see, with owner, profile, state, what it holds, whether it is pinned, what it did on GitHub (its draft pull request as a link, or its troupe/* branch, and whether it stopped after three red CI rounds; github-runs.md) and when it was last active; filtered by state and profile, searched, and paged. Metadata only: no role reads what a session said. Erase shows what goes (its key, every object version) and the forks that survive, then waits for the session's id to be typed. Its tab Mine, which is all a member's Sessions is: Offered to you from laptops: the sessions a laptop's person offered for steering, your own from your other computers and those shared with you, with whose laptop and whether it is there. The list is the plane's word as it changes: an offer made, withdrawn or gone offline shows within a second, with nothing asked again on a timer. Opening one follows its transcript and answers its approvals (once) and questions, sends a prompt, stops a turn and switches its agent, as you and never as an administrator (steering from another device). Invited to you: the sessions somebody invited you into by name, to follow or to steer, shown and taken away as it happens; a pod session opens from here as yourself, and a private one is read in the desktop app on your own computer, since only it can open it (sharing a session by name). Then your own sessions on the plane, each saying where it opens. Nothing there is an administrative call: each is what any client of yours asks, so you are shown nothing of anybody else's. |
| Runs and review | Every run a trigger started with nobody watching, newest first, across the teams you administer: its trigger, the repository and the issue that started it, how it stands (a skipped run with the cap that skipped it), its draft pull request with its CI rounds, what it spent and who has read it. A run's page reads its whole record, its session's GitHub record and a link to the session, and marks it read. Metadata only. |
| Connections | A platform admin's. Each MCP server people connect their own credential to, who has connected (whether, never what), and whose identity each session's calls go out as (admin.connections.list). Nobody can read or remove a person's credential: the plane holds none. |
| Profiles | Every profile, with its state, pods, image and the teams granted it; a profile's page reads every field of its spec. A platform admin makes, changes and deletes one (the delete after the warning that its grants go and its sessions turn read-only). The editor writes only the fields it shows and keeps the rest of the spec (MCP identities, GitHub permissions, model prices, a server's credential settings, anything newer than the console); it offers the plane's provider types and size classes, says what the chosen provider asks for and that model settings need an endpoint, and checks whether a pod can reach an MCP server (profiles-and-policy.md). The page ends with What a member sees: the plane's own answer to a member's app (profile.get, asked as you, so for no team), its agents and those it leaves out, its tool rules, its MCP servers with whose access each is called, the harness's tools with the ones a rule refuses marked, its model, reach and teams, the limits a session there is held to with whose number each is (the profile's or Troupe's default) and each agent's own, its GitHub permissions and caps where it has GitHub, and its two switches (a person's own tools, memory proposals), as tables to read. A team admin sees the profiles their teams are granted. |
| Configuration bundles | Each channel a profile follows, with its current version and who follows it. A version reads whole: its agents, skills and MCP servers, the Secret each server's credential needs, which profiles use it and which pods are behind, and what changed from the version before. A platform admin publishes a new version (JSON, checked and previewed first, with the teams that lose an entry they were allowed; typed by the channel's name when one does), publishes an older version's content again, and retires a version. A team admin reads them. |
| Triggers | A team's triggers, with what fires them, what they run as and when they last fired; a trigger's page reads every field and every revision of its document (admin.trigger.revisions). Make, change (only what moved is sent), pause, resume and delete one; a new webhook trigger's key is shown once. Run one now, after a confirm that says what it starts and spends (the run is linked on Runs and review), and Rotate a webhook trigger's key, after the warning that the old one stops at once: both work on a gitops plane too, and for a team admin on their own team's triggers (bundles-and-triggers.md §2). On a direct plane the Trigger resources in the cluster are listed beside the rows, In the repository, with their source, generation and whether they would pass (with the reasons); Copy makes a row from one, a webhook's key shown once, and a copied row reads from the repository, generation n, repository changed (with the diff and Re-copy), differs from the repository or gone from the repository (gitops.md). |
| Integrations | The plane's GitHub App (github.md): its App ID, API URL, installations, and its key by fingerprint and transit version. A platform admin tests it against GitHub (the App ID, that transit signs, that GitHub knows the App by that key, that every installation is one GitHub lists), changes it (only what moved is sent; a pasted key or webhook secret goes into OpenBao and is never shown back) and removes it, typed by its App ID; the newest deliveries are listed with what the plane did with each (admin.github.deliveries, never a body). Then the MCP servers more than one profile carries, every host anything dials against the cluster's policy with where it was declared, and each trigger's notification target checked again (admin.integrations.list). A team admin reads it. |
| Pods | A platform admin's. The pods behind each profile, with their state, release, bundle, sessions and disk. Drain stops a pod taking sessions and moves what it holds, typed by the pod's name. A pod a scale-down removed reads gone with when it was last heard and offers nothing; the plane forgets its row once it has been quiet past the drain timeout. And every profile, the cluster policy and every trigger as a repository would hold them, to bootstrap one before switching to gitops (gitops.md). |
| Provisioners and hosts | A platform admin's. What each substrate guarantees and does not (admission policy, network policy, egress by hostname, a disruption budget), what each profile's workers lack, and which teams may be granted a profile nothing is enforced on. The machines registered to a profile (single-machine.md): register one, and its enrolment secret and the control port's CA are shown once; rotate its secret, typed by its name; switch it off or on. |
| Budgets | Every team's spend against its ceiling, and what its artifacts hold against its storage quota. A platform admin asks which ceiling would refuse a person first (their own cap, the team's, the platform's, each with what is left) and sets a person's own monthly cap. |
| Teams | The teams you administer, searched by name, group or admin, with people, groups, profiles, admins and spend. A platform admin enables a group as a team here, under a name the plane will not mistake for another team's, from the list of groups seen in sign-ins that no team draws on yet, each with when it was last seen, so a new group is chosen by name; being listed grants nothing. A team has six tabs: Members and groups (link a group, flagged where it looks held twice; unlink one after the count of who loses the team, typed by the group's id), Access (grant a profile, warned when the plane will refuse one nothing is enforced on; revoke one after the warning that its sessions turn read-only), Admins, Limits (each limit in force with the rung that decided it and Why?; a shorter retention is typed by the team's name), GitHub (the team's repositories, GitHub) and, for a platform admin, Danger zone (what removing the team would take, then removal). |
| Identity | For a platform admin: who would administer the platform with a given group (how many people carry it, and whether you are one), the groups this plane has seen, and the people and groups that look held twice (the same email or name under two keys), each with where the rows came from and the mismatch at the provider that most likely made them. That is fixed at the provider; an adoption the plane refused on an externalId can also be Settled here, typed by the subject (admin.identity.adopt, routine-tasks.md). For both roles: a team's service principals, made and rotated (the secret shown once) and disabled, each typed by its subject; one whose sponsor left says it needs a sponsor. |
| Sign-in | A platform admin's. The identity provider: the URLs its registration needs, every sign-in setting with where it came from (a secret as set), changed behind the plane's check of the values in the form, saved anyway only when you say the provider is down, and put back to the deployment's. The SCIM connector: where the provider pushes, its status and last push; rotate its token (shown once), switch whether pushed groups become teams, and forget the token, typed by the base URL. |
| Policy and settings | Every platform setting by panel, named by its label with its key beneath, its value in its unit (dollars, minutes, days, on or off, a choice's words), with where it came from, the deployment's read-only and secrets as set. A platform admin changes and resets them, typing money in dollars and time in minutes, converted for the plane on save, and the preview and the audit note say the change in those words (Budget for the platform: $500.00 → $750.00; Decision 991); platform_admin_group is saved only once the check has passed for the value in the field. The ladder: for each setting more than one rung decides, the value in force, the rung that decided it and every rung that had an opinion, above every team or for one. A team admin reads it. |
| Client versions | Per kind of client (the terminal, the daemon, the desktop app), the recommended version, the minimum and the blocked versions (routine-tasks.md). A platform admin changes them; a team admin reads them. Below them, Your clients: which version of each of your own clients the plane last saw against its policy, which is all a member's Client versions has. |
| Organisation | The organisation's document for people's own machines: its defaults, below each person's own settings, each named by its label and asked for in its unit, with where each came from, and its enforced set, above everything a person sets (configuration.md). The keys the set may hold are the plane's list, each with what enforcing it means. Its per-tool permission rules (permissions) have their own editor: add, change and remove deny, ask and allow rules as a tool and a pattern, each checked as it is typed the way the plane checks it, then previewed in words and recorded. A platform admin changes them; a team admin reads them. |
| Audit | Who changed what and when, newest first, with every field that moved, a setting's and a team limit's by its name and in its unit (the key stays in the row's subject); narrowed by actor, kind and subject, searched, and read a hundred rows at a time. A platform admin can have the plane check the trail's hash chain, which names the first row that does not verify. |
Every change shows what will happen, then waits for its button; one that takes away something nobody can simply give back waits for a name to be typed as well. The plane's refusal is shown where it was made, with nothing written; and once applied, the console shows the change as the audit recorded it. A secret the plane answers once (a principal's, a machine's, the SCIM token) is shown once, with a button that copies it.
On a plane in gitops mode (gitops.md),
profiles and triggers are a repository's: the console shows them under Held in a
repository, with where they come from and what the plane made of each, and offers no
change, since the plane refuses one. A profile or trigger the cluster has no resource for
can still be deleted.
The console calls every administrative method the plane serves. The plane places every
method on an area of the console's map (Troupe.Plane.Admin.Console), and a test fails when
the plane serves a method no screen of the console calls.
Trying it without a cluster¶
From clients/gui:
pnpm console:fake # an identity provider and a plane, on loopback
pnpm console # then open http://localhost:5174 and sign in to the plane it printed
CONSOLE_AS=bob pnpm console:fake signs in as a team admin, and CONSOLE_AS=carol as
a member, who administers nothing and is shown what is theirs; a second laptop session is offered to
whoever is signed in fifteen seconds after it starts (OFFER_AFTER_MS). GITOPS=1 makes the fake plane one in gitops mode.