Skip to content

A profile's options

The parts of a worker profile beyond its image, size and endpoint: a profile that extends another and says only what differs, an identity of its own at an MCP server, a repository's agents and skills against the bundle's, a person's own tools on its pods, and per-tool rules every session there obeys. The fields themselves are in profiles and policy §1.

A profile that extends another

An organisation can keep one standard profile (the model, the egress, the MCP servers and the limits everybody gets) and give a team that needs more a profile that extends it and says only what differs (Decision 908). The plane resolves the two into the profile in effect, and that is all the cluster sees: the operator, admission and the workers get a flat WorkerProfile.

{"name": "data-team", "extends": "standard", "max_sessions": 10,
 "spec": {"egress": {"fqdns": ["warehouse.example.com"]},
          "llm": {"secretRef": {"name": "data-team-llm"}}}}
Field What the child gets
egress.fqdns, egress.gitHosts the parent's, and its own added; each still checked against the policy
mcpServers the parent's, and its own added by name. One with a parent's name replaces the parent's only with "override": true; otherwise the parent's is kept and the clash is reported
agents, skills, MCP servers and ACP agents in the bundle its pods load the parent's channel's, and its own channel's added by name (Bundles, below)
max_sessions, llm.maxTokens the lower of the two: a child can narrow a ceiling, never raise it; the preview and the effective view say so where a child's llm.maxTokens is higher
budget_micros the lower of the two; one set above the parent's is refused with a sentence
personalTools, repositoryOverridesBundle, memoryProposals a parent's forbid or false holds whatever the child says, and the preview and the effective view say so where the child says otherwise; otherwise the child's, or the parent's
image, size_class, provisioner, the other llm fields, storage.storageClassName, configBundleChannel, github, orgMount and any other field the child's where it sets one, the parent's where it does not (for github's caps and denied paths, see github.md §7)
llm.secretRef, mcpIdentities, grants, warm_workers never inherited: a key and an identity are each profile's own, in its own namespace, and a grant of the standard does not make a team a user of its extensions

An empty field is one the child does not set, so a child cannot take away what its parent has: if a team should have less, the standard is too wide. A chain is at most four profiles long, counting the one that extends nothing; a missing parent, a cycle and a longer chain are refused with a sentence.

  • Reading one. admin.profile.get answers spec and written as the profile wrote them (what to change and send back) and extended_by, the profiles that extend it. With "effective": true it adds effective: the chain, the profile in effect, and fields, every path and value with the profile it came from. Its problems says when the child has its model endpoint from a parent whose key it lacks, and identity_problems names an inherited client-credentials server the child has no identity for. The console's profile page shows "Extends" and where each field comes from; its editor leaves to the parent whatever is left empty.
  • Changing the parent. admin.profile.preview of the parent lists every profile below it in extended_by, each with its diff and the policy's verdict. admin.profile.put refuses a change that would leave a child the plane or the policy refuses, naming it; otherwise it rewrites each child's resource, and its pods roll as for any change. The audit has one profile.put, the parent's, with extended_by naming each child and what changed in it.
  • Bundles are composed (Decision 910). A child on its parent's channel, or naming none, loads that bundle as it is. A child on a channel of its own loads one the plane composes: the parent's channel's agents, skills, MCP servers and ACP agents, with its own channel's added by name. An entry named like one the parent's bundle has replaces it only where the child's channel's document says "override": true on it (an agent may say it in its frontmatter); otherwise the parent's is kept, and effective.bundle.problems says so. The MCP servers each profile in the chain wrote itself are a layer after its channel's, by the same rule, so a profile that extends nothing but wrote servers of its own has a composed bundle too. The plane publishes a composed bundle, when it differs, as a version of the child's own channel profile:<name>: its pods fetch and check it by hash and a session pins its version, as on any channel, and a publish or retire anywhere in the chain composes it again. The resource's mcpServers are the composed bundle's, so the reach and identity checks read what the pods load. profile: channels are the plane's: publishing or retiring one by hand, or naming one as a profile's channel, is refused. admin.profile.get with effective lists it in effective.bundle (channel, hash, the channels it is made from, each entry with the profile whose channel gave it); the console shows it as "The bundle its pods load".
  • Deleting the parent is refused (conflict, extended_by) while a profile extends it. Make each extend another profile, or none: a put without extends keeps the profile as it was in effect, following nothing from then on.
  • In gitops mode a manifest names its parent in spec.extends and says only what differs; the plane writes the profile in effect into the resource's status (gitops.md). admin.profiles.export writes a child's manifest that way.

Calling an MCP server as the profile

Some MCP servers take machine callers only through OAuth client credentials, want the client to prove itself with a signed assertion (a private key JWT, RFC 7523) rather than a shared secret, and grant tools per client. For those each profile gets its own system identity: its own client at the identity provider, with its own certificate and granted tools, so two profiles never share permissions (Decision 747). The bundle marks the server "credential_mode": "client_credentials" (bundles); the profile says who it is there.

spec:
  mcpIdentities:
    - server: jira                         # the bundle's name for the server
      clientId: 00000000-0000-0000-0000-000000000000
      scope: api://example-jira/.default   # optional
      tokenUrl: https://login.example.com/tenant/oauth2/v2.0/token   # optional
      transitKey: troupe-w-dev.jira        # <worker namespace>.<anything>
      keyVersion: 1                        # optional; absent is the key's latest
      certificateThumbprint: qIAESDPaFvTg7nQnau6q6AzzzpMg6PElJvINleJ0N2s
      algorithm: RS256                     # or PS256
      # subject: absent, so iss and sub are the clientId

A worker asks the token endpoint for a token with grant_type=client_credentials, the client id, the scope and an assertion: iss and sub the identity's subject (the client id when it has none), aud the token endpoint, five minutes' life, a fresh random UUID as jti, and the certificate's thumbprint in the header twice, as x5t#S256 and as kid (Entra reads the first, Authentik only the second; each ignores the other). An identity provider refuses an assertion whose exp is more than ten minutes ahead or whose aud is not exactly its token URL, so name tokenUrl as the provider spells it, trailing slash and all. OpenBao transit signs it: the worker sends the signing input and gets the signature back, so the private key never leaves OpenBao, not even into the worker's memory. The token that comes back names the server's client id as its aud (or azp). The worker keeps one token per server, renews it five minutes before it runs out (or at three quarters of its life, if that is sooner), asks again once after a 401, and sends it as Authorization: Bearer; it is never in a log, an error or the event log. Without tokenUrl the token endpoint is the one the server's authorization server publishes (named in its protected-resource metadata). tokenUrl's host is egress the policy must allow, and one found in metadata must be in egress.fqdns.

subject is needed with an identity provider that knows the system by one subject while each server is its own client there, as Authentik does: the clientId differs per server, and iss and sub are the one system identity, a name of at most 255 bytes. Leave it out for a provider, such as Entra, whose client is the system. In Authentik:

    - server: jira
      clientId: <the jira application's client id>
      subject: sys-dev                     # sys-<profile>
      scope: openid entitlements
      tokenUrl: https://auth.example.com/application/o/token/
      transitKey: troupe-w-dev.jira
      certificateThumbprint: qIAESDPaFvTg7nQnau6q6AzzzpMg6PElJvINleJ0N2s

Setting one up and rotating are on an MCP identity's key: make the key and certificate, import the key into OpenBao transit under <worker namespace>.<anything>, register the certificate with the identity provider, write the identity; to rotate, register the new certificate beside the old, import the next key version, and change keyVersion and certificateThumbprint in one change.

What is reported. A client_credentials server with no identity on the profile, or an identity without clientId or transitKey, with a thumbprint that is not one, another algorithm, a keyVersion that is not a positive number, a subject that is empty or longer than 255 bytes, or a tokenUrl that is not https (or http to loopback), is reported rather than refused, as a missing Secret is: by the operator's MCPIdentityMissing condition and in admin.profile.get's and admin.profile.put's identity_problems (the resource's schema refuses an empty or over-long subject outright). The pods start regardless and offer that server's tools once both halves are there. A worker that cannot get a token says which server and why: the token endpoint refused the client (with the provider's error), the transit key is not in OpenBao, the pod may not sign with it, or the server refused a tool the identity lacks.

A repository's agents and skills on a pod

A session's working copy may carry agents and skills of its own (.troupe/agents/*.md, .troupe/skills/<name>/, .agents/skills/<name>/), which arrive with a clone. On a pod the bundle's agents and skills, and the agents Troupe ships, beat them where the names are the same (Decision 826): a working copy's build.md replaces neither the bundle's build nor, where the bundle has none, Troupe's own, and its review-checklist skill does not stand in for the bundle's. The same holds for the pod's own config directory, and on a pod whose channel has nothing published. Other names are read as on a laptop.

A file that loses is not read. The session lists it, with the reason, in a files_skipped event, written at each activation whose list differs from the last one recorded:

{"files": [{"kind": "agent", "name": "build", "path": "/var/lib/troupe/workspaces/<id>/.troupe/agents/build.md",
            "reason": "the session's bundle has an agent named build, and on the platform the bundle's beats a repository's unless the profile allows the repository's"}]}

An agent named like a built-in gets the reason build is an agent Troupe ships, and on the platform Troupe's own beats a repository's unless the profile allows the repository's. The terminal and the desktop app show the event in the transcript as a note: how many of each kind, each file, and why.

A profile that wants the repository's files to win, over the bundle's and the built-ins alike, sets the switch:

spec:
  repositoryOverridesBundle: true

Only true turns it on, and admin.profile.put refuses a value that is not a boolean. The console's profile editor has it as a toggle. It rides the activation, not the pod: the plane reads it at every activation and sends it with the bundle pin, so a change reaches a session the next time it wakes and restarts no pod, and an ssh profile has it too.

Onboarding (troupe onboard, the question a session's start asks, and the onboard_write tool) refuses on a pod and says to onboard on your own machine and commit the result: the working copy is a clone the bundle beats, and the config directory is the pod's, read by every session it runs.

Commands have nothing to lose to yet: a bundle carries no commands, so a working copy's .troupe/commands/ are read on a pod as on a laptop, and a command named like an agent stays the agent's, which on a pod is the bundle's (Decision 763).

A person's own tools on a pod

A person signed in to an MCP server on their own machine can offer its tools to a session on a pod from the desktop app or the TUI: the session registers them as tools the client hosts (tools.register), and each call runs on the person's machine with their sign-in (security.md §8). A team whose pods should work only with what the profile names forbids it (Decision 862):

spec:
  personalTools: forbid

A session on those pods then refuses the offer before it asks the person anything, answering forbidden with setting: personalTools, the profile's name, and the sentence the profile <name> does not take a person's own tools (personalTools: forbid); only the profile's MCP servers are available. The pod logs one warning per refusal, with the session, the person and the tools; nothing is registered, and the session's own log records nothing. The desktop app shows the sentence where it would have said what is offered, the TUI shows it once as a note, and neither offers the person's servers to that session again while it stays open.

admin.profile.put and the resource's schema refuse any value but allow and forbid, and anything but forbid leaves the offer as it is. The console's profile editor has it as a toggle. Like repositoryOverridesBundle it rides the activation, so a change reaches a session the next time it wakes, restarts no pod, and applies to ssh profiles too; a session awake when it changes keeps what it had until then. The platform's managed_mcp_servers_only refuses the same offer on every profile at once.

Proposals to shared memory from a pod

An agent may propose an entry for its team's or the organisation's memory, for an administrator to accept or decline (Decision 1004). A profile whose sessions should propose nothing, a review or a trigger's, says so (Decision 1012):

spec:
  memoryProposals: false

The plane then refuses every proposal from a session on its pods, keeps nothing, and answers forbidden with the sentence the platform setting Agents may propose memory refuses with, naming the profile in its place: proposals to a team's or the organisation's memory are switched off for the sessions of the profile <name> (its memoryProposals is false); nothing was proposed, and where to remember it instead. Absent or true, the setting decides. A parent's false holds for every profile that extends it. The plane reads it at each proposal, so a change restarts no pod. A session on a person's machine runs on no profile, and only the setting turns its proposals off. The console's profile editor has it as Agents may propose memory.

Where the organisation keeps files

A server of the bundle that stores the organisation's files (a SharePoint, a document space) is marked "stores": "files", with "files": ["upload_document"] naming the tools that save one, all of them when left out (bundles):

{"name": "docs", "url": "https://mcp.example.com/mcp", "credential_mode": "person",
 "stores": "files", "files": ["upload_document"]}

An agent on the profile asked for a file puts it there first, before an artifact or the workspace, and names the tools in what it was told was open (where a file goes, Decision 956). Nothing is inferred from a tool's name. Writing to the store is the server's: Troupe calls the tool as it calls any other, under the same permission. A files without stores is refused at publish.

Per-tool rules on a profile

A profile may carry the per-tool rules a person's config carries (permissions), and every session on its pods obeys them (Decision 913, #724):

spec:
  permissions:
    deny: ["shell(curl)", "read_file(secrets/**)"]
    ask: ["mcp(issues.delete)"]
    allow: ["shell(mix test)"]

They are an enforced layer, the profile scope: of every rule that matches a call the strictest holds, deny over ask over allow, so nothing in a repository's .troupe/config.yaml loosens them, and a profile's allow stands under managed_permission_rules_only as the organisation's does. A refused call names the rule and the profile ("refused by the rule deny shell(curl), from the worker profile fixing"), and an asked one says so on its approval in the TUI and the desktop app. A deny for shell also refuses a command a person types with ! in a session on these pods (forbidden, setting: permissions); an ask does not, since the person typing it is who it would ask. A person sees these, and the rest of what is in force in a session (the profile's provider and models, the platform's switches, the session's terms), with troupe config --explain --session <id>, /settings in the terminal UI, or the desktop app's Settings pane.

admin.profile.put and the resource's reading refuse a rule the pods could not read, with the reader's sentence. The rules ride the activation like personalTools. A profile that extends another has its parent's rules as well as its own, each a scope of its own on the pods, so a child adds rules and cannot loosen or drop its parent's. The console's profile editor edits a profile's own rules, and its page lists every rule in effect with the profile it came from.

Which agents a profile has

A profile may say which agents exist on it, built-ins and its bundle's alike, by name (Decision 968):

spec:
  agents:
    allow: ["answer", "ask", "admin-support"]   # only these, in every mode
    deny: ["build"]                             # taken away; deny beats allow

allow present means only the names it lists exist on the profile's pods, primaries and subagents both; deny takes names away; absent is every agent the bundle and Troupe give, which is what every profile had before the field. An agent the rule excludes is not offered to a session, is refused by session.create with the primaries the profile could have offered, and is not loaded on the pod: it is in no delegate list, so no other agent reaches it under that name. The rule is the profile's statement that the agent is not there, which is why it reaches subagents too. A name no agent has today is kept, since a bundle may gain it; admin.profile.agents marks each agent offered or not and lists such names in unmatched. A name in both lists, or one that is not a name, is refused. The function agents (answer, ask, quick, librarian: mode: function, which Troupe starts for a job of its own and no session runs as its agent) are agents too: a deny: [librarian] turns the project brief's survey off on the profile, and where Troupe would start one the rule removed it says so once in the session's log instead. No grant narrows a function agent; profile.get lists those left as functions, admin.profile.agents marks them mode: function, and the built-in primaries are the files' mode: primary ones (build, orchestrate, plan, Decision 970).

Two profiles, as most are written. The lean one is the usual case: a profile for one job, whose bundle brings the one agent it needs, takes the coding agents Troupe ships away and keeps the rest (answer and ask are read-only and cheap, and harmless to leave):

apiVersion: troupe.dev/v1alpha1
kind: WorkerProfile
metadata: {name: company-info, namespace: troupe-system}
spec:
  image: {repository: ghcr.io/it-minds/troupe-worker, tag: 0.33.0-beta}
  configBundleChannel: company-info          # brings the agent `company-info`
  llm: {endpoint: https://llm-gw.example.com, provider: openai, model: chat-economy,
        secretRef: {name: troupe-llm-gateway, key: api-key}}
  agents:
    deny: [build, implementer, orchestrate, general, quick]

The fuller one says everything the lean one left to the defaults, for a profile that is allowed to change code but only through the agents it names, with the per-tool rules beside it, since the two are different statements: agents says who exists, permissions says what any of them may do:

apiVersion: troupe.dev/v1alpha1
kind: WorkerProfile
metadata:
  name: dev-reviewed
  namespace: troupe-system
  annotations: {troupe.dev/max-sessions: "12"}
spec:
  image: {repository: ghcr.io/it-minds/troupe-worker, tag: 0.33.0-beta}
  sessionsPerPod: 4
  resources: {requests: {cpu: 500m, memory: 2Gi}, limits: {cpu: "2", memory: 4Gi}}
  storage: {size: 20Gi, storageClassName: sbs-default}
  configBundleChannel: stable                # brings `pr-reviewer` and `release-notes`
  llm: {endpoint: https://llm-gw.example.com, provider: openai,
        model: chat-default, smallModel: chat-economy,
        secretRef: {name: troupe-llm-gateway, key: api-key}}
  egress: {fqdns: [github.com, api.github.com]}
  agents:
    allow: [build, plan, explore, reviewer, implementer, answer, pr-reviewer, release-notes]
    deny: [orchestrate]                      # listed to say so; deny beats allow
  permissions:
    deny: ["shell(git push)", "shell(curl)", "read_file(secrets/**)"]
    ask: ["shell(mix ecto.*)", "publish_artifact"]
    allow: ["shell(mix test)", "shell(mix format)"]

A profile that extends the fuller one may only narrow its list: allow: [plan, explore, answer] on the child leaves the parent's build behind for good.

A grant narrows what is left. A team's entitlements on its grant (bundles and triggers) are resolved after the profile's rule, so a grant can leave a team fewer of the profile's agents and never one the profile said is not there. session_created records the resolved primaries as entitlements.agents and the rule itself as agent_rule; session.activate carries both at every activation, so a change reaches a session the next time it wakes and restarts no pod, as the per-tool rules do.

extends. A profile that extends another has its parent's rule as well as its own and can only narrow: its allow is cut to the parent's where the parent has one, its deny adds to the parent's, and status.effective and admin.profile.get's effective carry the composed rule. The console's profile page shows it in one line ("Agents: all but build"); its editor has no field for it and carries it through a save as loaded, so it is written through admin.profile.put or a repository's manifest.