An organisation's document, from a plane's cached copy or a managed file at a fixed path, gives a machine defaults below the user file and an enforced set above the command line; only the keys the schema marks can be enforced, each a ceiling, and troupe config pull refreshes the cached copy rather than writing the user file¶
Decision 869 · accepted · 2026-10-11 · issue #122
Superseded in part
In part by 907.
The ladder¶
Lowest first: built-in defaults, org (the organisation's defaults:), user,
project, local, env, cli, enforced (the organisation's enforced:). A pod
(trust: :never) reads neither: its configuration is its profile's.
One format, two places¶
version: 1
defaults: { ... any key a user file takes, but trusted_workspaces ... }
enforced: { ... only the keys below ... }
enforced: takes a key only if the schema marks it; its value is type-checked the same
way and written out in full: {env:VAR} there refuses the load, because the person sets
their own environment. A key outside the two sections warns.
- The managed file is at a path fixed per system:
<system drive>\ProgramData\troupe\ managed.yamlon Windows,/Library/Application Support/troupe/managed.yamlon macOS,/etc/troupe/managed.yamlelsewhere. Windows's%ProgramData%is a variable a person can set for their own processes, so the drive is read from the registry'sSystemRoot(HKLM, an administrator's), falling back toC:.
No override in a release. Neither path is moved by a variable or a flag. The
application environment (:troupe_core, :organisation) moves them only in a test run,
which is recognised as the :mix application started with its environment test: a
release carries no Mix, so ERL_FLAGS, which can set any application's environment, moves
nothing there either.
Which source wins when both exist¶
The plane's, as recommended, for defaults: its org layer is read after the managed
file's, so it wins key by key and the file's other defaults stay. For limits the
choice is not the plane's alone: where both enforce a key, the stricter holds (the lower
ceiling, the tighter end of an order), and where both fix provider or base_url, the
managed file's holds and the plane's copy warns. Letting the plane's set replace the file's
would let a person on a managed machine lift the file's limits by signing in to any plane,
their own included; the managed file is the one a person cannot change, and the cache is
a file in their own state directory.
The enforceable keys, and why each¶
Troupe.Protocol.Organisation holds the list, with what enforcing each means and its
type, in the protocol app because the plane (refusing an administrator's set) and the
machine (holding to it) must read it the same way, as Decision 868's ClientUpdate is.
| Key | Kind | Why it is on the list |
|---|---|---|
approvals |
order wait < deny |
what an unattended call does is the organisation's risk; deny may not be loosened |
provider, base_url |
fixed | where requests and code go is the organisation's data boundary (a gateway that logs and bills) |
managed_mcp_servers_only, managed_permission_rules_only |
order off < on | the two switches the plane already sets for its pods' sessions (its sessions settings); the same word now reaches laptops |
max_tokens, max_turns, wall_clock_ms, max_depth |
ceiling | the budget ceilings: what one call, one agent's run and a delegation tree may cost |
A ceiling lets a lower layer be stricter: a lower max_turns, deny under an enforced
wait, a switch on under an enforced off. A fixed value has no stricter end. With
provider or base_url fixed, a named provider of another type or at another URL is
refused, as a provider whose key is unset is (a :refusal naming it): otherwise
models.default: mine/x would route around the fix. Nothing else is enforceable; in
particular not auto_approve, which the issue's prose mentioned and the maintainer's list
left out.
Unmarked keys. On the plane, client_enforced naming one is refused at the put with
Organisation.refusal/1's sentence and nothing written. On the machine the key is not
enforced and warns with the same sentence: a newer plane that marks more keys must not
refuse every session of an older client, and the warning says what was skipped.
Held, said once, shown¶
Every value a layer gave an enforced key that goes past the limit is marked on the ladder as ignored ("held to 25 by your organisation (source)") and warned about once, naming that file (or variable, or "command line"), the key and the organisation's value. A struct default past the limit is held with no warning: nobody set it.
config.set of an enforced key is refused at every scope, whatever the value, with "set
by your organisation".
Refresh, and troupe config pull¶
The daemon refreshes its copy after every identity.link that brings a plane token, once
the handshake has not refused this version (Decision 868), before erasures. A plane that
does not answer leaves the copy. A new copy that changes a key is announced as
config.changed with scope: "org".
troupe config pull refreshes the copy instead of writing the user file, as
recommended: a copy in the user file outranks the organisation's defaults, is never
updated, and cannot carry the enforced set. It fetches me.client_defaults with the
terminal's own sign-in, as before, and hands the answer to the daemon's new
config.organisation, which keeps it through the same writer as the daemon's own refresh
(so there is no race with the token hand-over). It prints what the machine now takes and
names any key the person's own files set over the organisation's defaults (shadowed),
which is how a person who pulled into their file before learns to remove the copy. Not
chosen: the daemon fetching on pull itself, which needs the token handed over first and
would race the client's asynchronous hand-over.
What this is not¶
The enforced set is the organisation's word honoured by Troupe, not a lock against a person on a machine they administer: the plane's copy is a file in their own state directory, and they choose the build they run. A managed file owned by an administrator on a machine its person does not administer is the strong form. A copy signed by the plane, checked offline with an expiry, is #66's channel document's job.
Governs: apps/troupe_protocol/lib/troupe/protocol/organisation.ex, apps/troupe_core/lib/troupe/config/org.ex, apps/troupe_core/lib/troupe/config/layers.ex, apps/troupe_plane/lib/troupe/plane/settings.ex