Which file wins¶
The part of configuration that says whose word a setting is: what your organisation suggests and what it holds you to, which keys wait until you trust a workspace, every file Troupe reads, and the ladder that decides between two of them that say different things. Every key is in the reference.
Your organisation's defaults and limits¶
An organisation speaks at both ends of the ladder. Its defaults sit below your own file: they are what a machine starts with, and anything you set wins over them. What it enforces sits above everything, the command line included. That is a guardrail, not a lock: a plane's copy is a file in your own state directory, and only the managed file is out of your reach (security).
Only these keys can be enforced, and each but the rules is a ceiling:
| Key | Enforced, it means |
|---|---|
max_tokens, max_turns, wall_clock_ms, max_depth |
the most it may be: you may set a lower number, not a higher one |
approvals |
deny may not be loosened to wait |
managed_mcp_servers_only, managed_permission_rules_only |
on may not be turned off |
provider, base_url |
what it is; a named provider at another URL, or of another type, is refused too |
permissions |
its per-tool rules are added to yours, and none of yours loosens one of them |
A file, a variable or a flag that tries to go past an enforced value is held to it, with
one warning naming the file, the key and the organisation's value, and config.set
refuses it from either client. When a session reaches an enforced max_turns or
wall_clock_ms, the question whether to go on offers only what stays under it, says the
limit is your organisation's and where it came from, and turns away a larger amount,
no limit and an allow past it. A model entry's own max_output can lower an enforced max_tokens for
its model, not raise it. An enforced max_tokens bounds the whole of every model call, a
compaction's summary and a model's thinking included
(how thinking is fitted under it).
troupe config --explain KEY shows both ends with where they came from:
max_turns = 25
default 40
user 80 /home/me/.config/troupe/config.yaml
ignored: held to 25 by your organisation (https://plane.example.com)
enforced 25 https://plane.example.com <- in effect
The organisation's word comes from two places. Signed in to a plane (troupe login), the
daemon fetches its document whenever a client connects and keeps a copy, used as it is
when the plane cannot be reached; troupe config pull fetches it now, and writes nothing
into config.yaml. What a pull before 0.14 wrote there is your own setting and wins over
the organisation's defaults; pull names those keys, and taking the lines out follows the
organisation again. Without a plane, an administrator writes a managed file. Where both
say something, the plane's defaults win over the file's, the stricter of two limits holds,
and a provider or URL both fix is the managed file's. The format, and how an administrator
sets either, is on the administrator's
configuration page.
Trusted workspaces¶
A repository's files come from whoever wrote the repository. The keys that decide what a session may do without asking, where requests go and with which key, what runs on this machine and what may be read are read from a workspace's own files only once you trust the workspace:
- approvals:
auto_approve,approvals,delegation,managed_permission_rules_only,managed_mcp_servers_only,watch,watch_auto_approve - endpoints and credentials:
provider,base_url,api_key,auth,providers,identify - commands to run:
mcp - paths:
read_roots,state_dir,fake_script
Until then they are ignored with a warning that names the command to run, and the rest of
the file applies. Trusting a workspace is a line in the user file, and
trusted_workspaces is read only from there:
trusted_workspaces:
- ~/src/my-service
- ~/src/work # a directory trusts everything under it
troupe config trust [PATH] # add the workspace (default: this directory)
troupe config untrust [PATH] # remove it
troupe config trust --list # what is on the list
trust and untrust change that one list, keep the rest of the file and its comments,
and keep the file as it was beside it as config.yaml.previous; a list written in
brackets is written out one item a line. A git worktree of a trusted checkout is trusted
too, which is where a branch session works, and trust in a worktree adds the checkout.
untrust does not remove a directory above the workspace, which trusts other workspaces
too; it says which one still does. A session on a team's pod never reads these keys from a
project's file, trusted or not: its provider and key come from its profile.
A workspace's agents and MCP servers wait for the same answer. A .troupe/agents/<name>.md
whose permissions: sets a tool to auto runs it unasked only once the workspace is
trusted; until then the tool asks as it would without the file, and agents.list gives
the agent a note naming the command. Its ask and deny apply either way, and your own
<config>/agents/ and the built-ins are not the workspace's. Its servers' auto, and
what its mcp.json or skills.json includes from outside the repository, wait too
(MCP servers and skills).
Trusted or not, a workspace's .troupe/agents, commands, workflows and skills are
read only where they really are inside it: a file there, or the whole directory, that
links elsewhere on the machine is not read, and is listed with why in agents.list,
skills.list and the session's log. Reaching outside the repository is what a trusted
skills.json is for.
Every file Troupe reads¶
In the order each kind is read, and what happens when two say different things:
| File | Layer | What it is for | On conflict |
|---|---|---|---|
the organisation's defaults: (the managed file, then the plane's organisation.json), <config>/config.yaml, <workspace>/.troupe/config.yaml, .troupe/config.local.yaml, the environment, the command line, the organisation's enforced: |
settings | every key below | later beats earlier; maps merge by key, null removes, a list replaces; trusted keys come from a workspace's files only once it is trusted |
<config>/mcp.json, then <workspace>/.troupe/mcp.json |
MCP servers | your servers, then the workspace's, over mcp: in config.yaml |
the same name merges key by key, the workspace's file last; a workspace's servers run only once you allow them |
a profile's bundle, ~/.agents/skills/, each .agents/skills/ from the repository root down to the workspace, <config>/skills/<name>/SKILL.md, <workspace>/.troupe/skills/ |
skills | what a skill tool may read | one name, the highest on the ladder; the others listed as skipped |
Troupe's built-in agents, a profile's bundle, <config>/agents/*.md, <workspace>/.troupe/agents/*.md |
agents | the agents a session may run | a file at a higher layer replaces the same name below it |
<config>/commands/*.md, <workspace>/.troupe/commands/*.md |
commands | the slash commands you and the repository define | one name, the workspace's; a built-in's or an agent's name is theirs |
<workspace>/.troupe/workflows/<name>.json |
workflows | the steps workflows.list offers |
one name, one file |
<config>/AGENTS.md, the repository root's AGENTS.md, one per directory down to the workspace and to each file the conversation worked on, each directory's .agents/AGENTS.md before its own and its .troupe/rules/*.md after it, and the files each imports with @path |
instructions | what the people who work here wrote for agents | all apply; the nearer wins where two disagree; the nearest kept whole when the budget runs out. Other tools' files are not read: troupe onboard brings them in once (instruction files) |
<workspace>/.troupe/memory/facts.jsonl, and its view .troupe/memory.md |
instructions | the project brief Troupe's agents write, as facts | its commands and conventions read after the instruction files, the rest through recall; never authoritative, read_file and grep are; an edit to the view is read back as facts |
Which one wins¶
Where two places say different things, Troupe takes it from the one higher on this ladder, lowest first:
- Troupe's built-ins: the agents that ship with it.
- A profile's bundle, on a team's pod. There the bundle's agents and skills beat the
repository's
.agents/and.troupe/unless the profile allows the repository's. .agents/:~/.agents/skills, then each.agents/skillsfrom the repository root down to where the session was started, the nearest highest; and each directory's.agents/AGENTS.md.AGENTS.md: the repository root's, then each directory's on the way to the work, the nearest highest.- Your
<config>/:config.yaml,mcp.json,skills/,agents/,commands/. - The repository's
.troupe/: the same files,rules/andmemory.md.
The last two are Troupe's own files, so they beat what a convention shared with other
tools says. What has a name (an agent, a skill, a command, an MCP server) comes from the
highest step that has the name, and the ones below it are not used: skills.list lists
each skill a higher one hid as skipped, naming the one that is used. Instruction files
have no name to lose: every one applies, and the higher comes later in the prompt, wins
where two disagree, and is kept whole first when the budget runs out. Your own
<config>/AGENTS.md is the exception, read first and so below the repository's files: it
is about every repository, and theirs is about this one.
Beside the ladder, a built-in command's name, or an agent's, stays theirs whatever a file
says, and config.yaml's settings have the layers of the files above and
below them.