Skip to content

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_URL from troupe-plane-database. TLS only with TROUPE_DB_SSL=true; pool TROUPE_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-upgrade hook Job, troupe-plane-migrate (kept with its logs on failure), never at boot. Troupe.Plane.Release.rollback/2 exists; 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-store in troupe-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, and llm.secretRef for the key (profiles-and-policy.md §1). The endpoint's host must be in allowedEgress.
  • llm.provider is one of the provider types a person's own machine takes (anthropic, openai, ollama, openrouter, azure_openai, gemini, fake), and nothing else. For azure_openai the endpoint is the resource's own address; ollama takes no key, so its profile has no llm.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.
  • openai posts to <endpoint>/v1/chat/completions with a bearer token and stream_options.include_usage; anthropic to /v1/messages with x-api-key. /v1 is not doubled.
  • The request id comes from x-litellm-call-id or x-request-id. The cost comes from the cost LiteLLM writes into a streamed call's last usage chunk, which openai asks for on every call to a gateway (x-litellm-include-cost-in-streaming-usage: true, so the gateway needs no setting), or from the x-litellm-response-cost header; 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 no llm.prices for the models it prices. A gateway that names no cost either way is priced from the profile's llm.prices, marked priced_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.reconcile compares a window of recorded usage with the gateway's GET /spend/logs by request id and exits non-zero over 1 000 000 micros of drift. It reads :troupe_plane, :gateway (base_url or spend_url, and key), which no configuration here sets, so it answers :no_gateway_configured until 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.