Skip to content

Administrator documentation

For whoever operates a Troupe deployment: the Helm chart, the PostgreSQL, object storage, OpenBao and identity provider beside it, and the teams, profiles, policy, bundles, triggers and backups on top.

Document What it covers
installing.md A cluster with nothing on it, to a first team in the console; a worked example on managed services
worker-sandbox.md What the nodes must give bubblewrap: the workers' seccomp and AppArmor profiles and user namespaces, what each allows, a cluster check, and what each refusal means
configuration.md Every environment variable, Helm value, platform setting, expected Secret, port and NetworkPolicy
client-config.md The config.yaml a session reads, and the defaults and limits an organisation gives people's machines
console.md The console at /console: where it is, how it is signed in to, and what each area does
roles-and-permissions.md Identity from the provider, admin roles, service principals, break-glass, session roles, how each surface authenticates, RBAC, the workers' and people's OpenBao policies, the admin methods
profiles-and-policy.md Worker profiles, what the operator creates, conditions, upgrades and drains, TroupePolicy, team volumes, provisioning, sizing
profile-options.md A profile that extends another, an MCP identity of its own, a repository's agents and skills, a person's own tools, memory proposals, per-tool rules, which agents it has
mcp-identity-keys.md Making, registering and rotating the key a profile signs its MCP client assertions with
gitops.md Profiles held in a repository: what the plane reads, the manifests, and switching a running plane
bundles-and-triggers.md Config bundles and MCP servers, triggers and the scheduler, unattended terms, budgets
integrations.md What the identity provider, OpenBao, PostgreSQL, object storage, the LLM gateway, Kubernetes, MCP, SCIM and the GUI require
openbao.md What OpenBao must grant the plane, generated from the code that checks it at start and on the Overview, and the lines an OpenBao administrator runs
github.md The plane's GitHub App: registering and installing it, giving the plane its key, the read-only token a session clones its repository with, and how far a run may go
github-runs.md The fix loop: a troupe/* branch, a draft pull request and its CI, never a merge; and GitHub as the trigger
authentik.md Connecting a plane's sign-in and provisioning to Authentik, in order
single-machine.md A worker on a machine you already have, and what it gives up
plane-light.md The plane and its own worker on one machine from one compose file, for an office without a cluster, and what that gives up
upgrading.md From one release to the next: the backup, the CRDs, the chart and its migration, what to watch, what the plane checks, going back, and the restore
backup-restore.md Where state lives, what can be rebuilt, restore procedures
monitoring.md Health endpoints, signals, the audit log, logs worth alerting on, a troubleshooting table
routine-tasks.md Step lists: teams, principals, bundles, drains, settings, client versions, lock-outs, SCIM, rotations, erasure
security.md For a security reviewer: what Troupe does unasked and never does, a worker's isolation and egress, keys, signed releases, unsigned apps, the limits' strength, logs and erasure

Also: ../a2a.md and ../egress-allowlist.md.

Before the first helm install

  1. The chart makes no Secret. Every one in configuration.md Part D must exist in troupe-system first; the operator copies those a worker namespace needs into it, a model or MCP key only once it is labelled troupe.dev/worker-secret=true.
  2. CRDs are installed once by Helm and never upgraded: kubectl apply -f charts/troupe/crds/ on every upgrade.
  3. Name the ingress controller's namespace in operator.ingressNamespace and the operator labels it troupe.dev/ingress=true; without that label the network policies keep the controller from the console, the API, /app and every worker. Left empty, the label is yours, and each profile and the Overview say so until it is there.
  4. Platform admin comes from an identity-provider group carried in a claim; whether the claim needs a scope is the provider's (integrations.md §1).
  5. Bucket versioning must be on, or erasure's promise means nothing.
  6. SecretMissing names a Secret a worker namespace lacks and where it was looked for.
  7. Nothing restarts a drained worker pod on the current revision. After admin.pod.drain, delete the pod; one behind a new revision the operator replaces.
  8. Principals, settings, the audit trail and triggers live only in PostgreSQL (in gitops mode a trigger's definition is the repository's). The session index can be rebuilt from object storage; they cannot.
  9. There is no metrics exporter, backup CronJob or OpenBao snapshot in the repository.
  10. Read security.md before people install the clients: what Troupe does unasked, how releases are verified, and how to open the unsigned apps.