Integrations¶
Every external system a deployment talks to, and what the code requires of it. Variables and Helm values are in configuration.md.
1. Identity provider (OIDC)¶
Troupe is a plain relying party. Of the provider it needs:
| Requirement | Why |
|---|---|
Discovery at <issuer>/.well-known/openid-configuration, naming the same issuer, with a jwks_uri |
tokens are verified against the JWKS, cached and refetched at most once a minute after a bad signature; iss is checked exactly |
| Device authorization grant for a public client | the TUI signs in from a terminal; the plane publishes the device and token endpoints at /.well-known/troupe |
| Authorization code with PKCE for a public client, no secret | the console and the GUI redeem the code from the page and hand the id_token to /auth/exchange, so openid must be in scope; the plane itself redeems nothing, and a confidential client, a client secret and a redirect URI of the plane's own (/admin/callback, from earlier releases) are not needed |
| A group claim in id tokens | admin and team membership are read from the claim groups_claim names. A token without the claim leaves memberships as they were, so an MCP client's access token needs it only to keep them current. Whether it takes a scope is the provider's: Authentik's does (authentik.md), and asking Entra for a groups scope refuses every sign-in (AADSTS650053) |
Redirects for the GUI (<base_url>/app, the chart's default), the console (<base_url>/console) and OAuth-capable MCP clients (loopback), the first two as a single-page application's |
all sign in in a browser |
For MCP: a provider access token whose audience is the client id, api://<client_id> or <base_url>/mcp, and the scope <base_url>/mcp/admin (or plane.oidc.mcpScope) |
an MCP client sends https://<plane>/mcp as RFC 8707's resource. On Entra that means <base_url>/mcp as an identifier URI beside api://<client_id>: it refused the older api://<client-id>/admin pairing (AADSTS9010010) |
Default scopes are openid profile email offline_access; offline_access is what gets a
client a refresh token. The person is the claim subject_claim names, sub by default
and oid on Entra, and SCIM's externalId has to carry the same value or the person SCIM
creates and the person who signs in are two rows
(configuration.md).
A sign-in that finds nobody under its subject takes over the row SCIM gave that value as
externalId only when the row's email or userName agrees with the token's email or
preferred_username (upn where there is none). On Entra, check that the provisioning
mapping sends objectId as externalId and the UPN as userName, and that the token
carries email or preferred_username; a pair it would not merge is listed by
admin.identity.duplicates and settled as in routine-tasks.md.
admin.identity.check runs four timed checks — discovery names the same issuer, the JWKS
has keys, the configured endpoints match discovery, and how many known people carry the
admin group (and whether you do) — and prints the redirect URI to compare with the
registration by eye. With a group argument it tests a candidate before you save it. The
console's Sign-in screen configures all of this at runtime, behind the same
check. Authentik specifically: authentik.md.
2. OpenBao¶
| Piece | Requirement |
|---|---|
Transit at transit, key troupe-session-tokens, ecdsa-p256, not exportable |
the plane signs plane tokens with it and publishes every key version as its JWKS |
Transit key troupe-plane-signing, ed25519, made by the plane on first use |
the plane signs the version policy and the organisation's document with it, served at /.well-known/troupe-signing-key; machines pin it at sign-in. The console's Integrations shows its fingerprint and rotates it |
KV v2 at secret |
per-session data keys at troupe/teams/<team>/sessions/<id>, and a private session's at troupe/people/<name>/sessions/<id>; erasure deletes the metadata path so every version goes |
Kubernetes auth at kubernetes, with a reviewer JWT (a ServiceAccount bound to system:auth-delegator) |
without one every login is permission denied and nothing says why |
Role troupe-worker (ServiceAccount troupe-worker, any namespace, audience troupe-kms), or with bao.workerRolePerProfile one role troupe-worker-<profile> per profile, bound to its namespace |
worker pods log in with their projected kms-token under the role in TROUPE_BAO_ROLE, cache the client token until shortly before its lease ends, retry a 403 once after a fresh login |
Role troupe-plane (ServiceAccount troupe-plane in troupe-system), with the plane and signing policies |
the plane logs in with its projected bao-token, caches the client token, retries a 403 once after a fresh login |
JWT auth at jwt, role troupe-person, keyed with the transit key's public half |
a person's daemon logs in with an assertion the plane signs, for their private sessions' keys and their own MCP credentials at troupe/people/<name>/mcp/<slot> (Troupe.KMS.Policy.person_role/2) |
A transit key per MCP identity, <worker namespace>.<name> |
a profile that calls an MCP server as itself signs with it (profile-options.md) |
The policies are in roles-and-permissions.md §8;
the commands, in development shape, in dev/kind/dependencies.yaml. A plane with neither
a static token nor a readable projected token logs one error naming both and answers
/.well-known/jwks.json with 503.
One replica with Raft is enough; the seal, and what a restart costs, are in installing.md §6. There are no Raft snapshots (backup-restore.md).
3. PostgreSQL¶
DATABASE_URLfromtroupe-plane-database. TLS only withTROUPE_DB_SSL=true; poolTROUPE_POOL_SIZE, 10 per replica plus the migration Job's — lower it for a small managed instance. Neither has a Helm value.- Migrations run in a Helm
pre-install,pre-upgradehook Job,troupe-plane-migrate(kept with its logs on failure), never at boot.Troupe.Plane.Release.rollback/2exists; nothing calls it. - No extensions. Session content is never stored here. Managed PostgreSQL with PITR is the recommendation.
4. Object storage (S3)¶
- S3 with SigV4. Layout
sessions/<id>/{manifest.json, segments/…, snapshots/…, workspace/…, blobs/…}: segments AES-256-GCM under a per-session key, manifests plaintext. Workers write (seal every 60 s and at a turn's end, snapshot every 500 events, archive the workspace at dormancy); the plane reads manifests to rebuild its index and to erase. - Private sessions are sealed from people's own machines, through URLs the plane
presigns against
TROUPE_OBJECT_ENDPOINT, so that endpoint has to be reachable from their machines too, not only from inside the cluster. - Versioning must be on. Erasure destroys the key first, then every version; without versioning "every version" means nothing.
- Credentials
troupe-object-storeintroupe-system, which the operator copies into every worker namespace. TROUPE_OBJECT_REGION(objectStore.region) reaches the plane and every worker.- No lifecycle or replication rules are configured by anything here.
5. LLM gateway¶
Troupe keeps no price table of its own; a profile names any OpenAI-compatible or Anthropic
endpoint, and, for models that endpoint does not price, llm.prices.
- Per profile:
llm.endpoint,llm.provider,llm.model, andllm.secretReffor the key (profiles-and-policy.md §1). The endpoint's host must be inallowedEgress. llm.provideris one of the provider types a person's own machine takes (anthropic,openai,ollama,openrouter,azure_openai,gemini,fake), and nothing else. Forazure_openaithe endpoint is the resource's own address;ollamatakes no key, so its profile has nollm.secretRef. The console's profile editor offers them all (admin.profile.choices) and asks each only for what it needs, and the provider offered to people's own machines (client_provider) takes the same names.openaiposts to<endpoint>/v1/chat/completionswith a bearer token andstream_options.include_usage;anthropicto/v1/messageswithx-api-key./v1is not doubled.- The request id comes from
x-litellm-call-idorx-request-id. The cost comes from thecostLiteLLM writes into a streamed call's last usage chunk, whichopenaiasks for on every call to a gateway (x-litellm-include-cost-in-streaming-usage: true, so the gateway needs no setting), or from thex-litellm-response-costheader; where both name one, the stream's counts, since it is what the gateway wrote to its own spend log. A LiteLLM gateway therefore needs nollm.pricesfor the models it prices. A gateway that names no cost either way is priced from the profile'sllm.prices, markedpriced_locally. Without any the cost is 0, the pod's log says so once a session, and without an id the id is synthetic. mix troupe.ledger.reconcilecompares a window of recorded usage with the gateway'sGET /spend/logsby request id and exits non-zero over 1 000 000 micros of drift. It reads:troupe_plane, :gateway(base_urlorspend_url, andkey), which no configuration here sets, so it answers:no_gateway_configureduntil someone does.
6. Kubernetes¶
| Item | Requirement |
|---|---|
| CNI | one that enforces NetworkPolicy (kind's does not, silently); Cilium for egress by hostname |
| Version | ≥ 1.30 for ValidatingAdmissionPolicy; admission.install: false leaves the operator's check alone. CI validates the chart against 1.31 |
| CRDs | installed by Helm once and never upgraded: apply charts/troupe/crds/ on every upgrade |
| ingress-nginx | 3600 s proxy timeouts and a 16m body (installing.md §6); name its namespace in operator.ingressNamespace, which the operator labels troupe.dev/ingress=true |
| cert-manager | a ClusterIssuer, letsencrypt in the example: HTTP-01, one certificate per pod hostname, no wildcard |
| Storage classes | a block class (ReadWriteOnce) for pod disks, a file-storage class (ReadWriteMany) for team volumes, and one for OpenBao's Raft volume; the policy lists what profiles may name |
| Nodes | what bubblewrap needs, since every command on a pod runs in it and a pod that cannot start it refuses every command (Decisions 832 and 890): unprivileged user namespaces, the chart's seccomp profile and, where nodes enforce AppArmor, its AppArmor profile, and user namespaces for pods (Kubernetes 1.33+, containerd 2.0+, Linux 6.3+, storage that takes idmapped mounts) (installing.md §0) |
7. MCP¶
Servers a bundle declares (Troupe as client) are declared once in the bundle, projected
onto the profile by the plane, injected by the operator, and discovered by the pod over
streamable HTTP. You create the troupe-mcp-<server> Secret in troupe-system, labelled
troupe.dev/worker-secret=true, which the operator copies into each worker namespace, and
put the host in allowedEgress (bundles-and-triggers.md §1).
A person's own servers are called from their machine, with their sign-in, and offered
to a team session from there unless its profile sets personalTools: forbid
(security.md §8).
The plane as an MCP server (POST /mcp): every admin method as a tool, the same actor
as /rpc, no session content. An OAuth-capable client needs only the URL and the app
registration's client id:
claude mcp add --transport http troupe https://<plane>/mcp --client-id <app registration> --callback-port 33418
It learns where to authenticate from the 401's WWW-Authenticate … resource_metadata= and
the RFC 9728 document at /.well-known/oauth-protected-resource. Destructive tools need
confirm. POST /mcp/session is a second door, for an agent already inside: four tools
(session_create, session_get, sessions_list, trigger_fire) as the caller, with a
plane token.
8. SCIM¶
| Item | Detail |
|---|---|
| Endpoints | /scim/v2/Users[/:id] and /scim/v2/Groups[/:id]: create, list with a filter, replace, patch, delete. GET /scim/v2/ServiceProviderConfig (RFC 7643 §5) says what the service does: patch supported, bulk not, a filter supported with at most 200 resources a page, changePassword, sort and ETags not, the bearer token. GET /scim/v2/ResourceTypes[/:id] lists User and Group |
| Token | minted on the console's Sign-in screen (admin.scim.rotate, shown once, kept as a salted hash), or the deployment's TROUPE_SCIM_TOKEN. Either opens the door; neither, and every request is 401 |
| Status | admin.scim.get: the last authorised request; teams_from_groups (off by default) makes a pushed group a team |
| Semantics | the subject is externalId, else userName, and must match the claim subject_claim names (oid for Entra, §1); a resource is addressed by the id the plane answered with; a push replaces a group's members, a PATCH adds and removes them; a push or a PATCH setting active to false deactivates the person, keeps the row and stops the principals they sponsor; a push that finds nobody under its subject but somebody under its externalId updates that person when their email or userName agrees with the push's, so a plane holds one row per externalId, and is refused 409 (uniqueness) when neither does, audited as person.adopt_refused and listed by admin.identity.duplicates, as is a push onto a row a sign-in made under the value while another row holds the externalId, 409 naming both (Decision 906); a replace (PUT) changes the person at its id, and one naming another subject is refused (mutability); a subject starting removed: or svc: is refused (invalidValue); deleting a user removes the row and leaves a tombstone: their sessions turn read-only under a "removed person" owner, they administer nothing, the principals they sponsor stop, no trigger's notify names them, their spend is counted under the tombstone, and the audit trail keeps their name; somebody pushed later under the same subject is new. Deleting a group removes it and disables a team drawn from it alone (Decision 899) |
| Answers | as RFC 7644 has them: a create 201 with the resource and its Location, a replace or a user's PATCH 200 with the resource, a group's PATCH and a delete 204, and an id the plane does not have 404. A POST of somebody the plane already knows, such as a person who signed in before their first push, updates them and is still 201 |
| Filter | one <attribute> eq "<value>": userName (in any case) or externalId on users, displayName (in any case) or externalId on groups; anything else is refused with invalidFilter. excludedAttributes=members leaves a group's members out |
| PATCH | add, replace and remove, with a path or a value object, as RFC 7644 and Entra write them (Replace, "False", members[value eq "<id>"]). It changes what a push would: a user's userName, externalId, displayName, email and active, a group's displayName and members; other attributes are accepted and ignored. One it cannot apply is refused whole with SCIM's error body and a 400, and so is one that would key a person on another subject (Decision 754) |
| Not supported | pagination (a filtered list answers its first 200 with totalResults counting every match; an unfiltered one answers every resource), sort, bulk, ETags, /Schemas |
| Without SCIM | sign-in builds the same rows from the group claim; a person who has left is only noticed at their next sign-in |
9. The GUI¶
The chart serves clients/gui at gui.basePath (/app) on the plane's host — same
origin, so no CORS entry, and the chart tells the workers to admit the plane's origin. A
GUI served from anywhere else needs its origin in plane.corsOrigins and in
operator.workerAllowedOrigins (a worker admits no page whose origin is not listed), and
its redirect registered at the identity provider, which also has to allow its origin for
the device grant. The desktop app needs neither list. The desktop app updates itself, and
signed in follows the version the plane recommends for desktop
(routine-tasks.md). The plane
answers CORS on /.well-known/<doc> paths, not on
/.well-known/oauth-protected-resource/mcp.