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.getanswersspecandwrittenas the profile wrote them (what to change and send back) andextended_by, the profiles that extend it. With"effective": trueit addseffective: the chain, the profile in effect, andfields, every path and value with the profile it came from. Itsproblemssays when the child has its model endpoint from a parent whose key it lacks, andidentity_problemsnames 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.previewof the parent lists every profile below it inextended_by, each with its diff and the policy's verdict.admin.profile.putrefuses 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 oneprofile.put, the parent's, withextended_bynaming 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": trueon it (an agent may say it in its frontmatter); otherwise the parent's is kept, andeffective.bundle.problemssays 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 channelprofile:<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'smcpServersare 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.getwitheffectivelists it ineffective.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 withoutextendskeeps the profile as it was in effect, following nothing from then on. - In gitops mode a manifest names its parent in
spec.extendsand says only what differs; the plane writes the profile in effect into the resource's status (gitops.md).admin.profiles.exportwrites 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.