Skip to content

The config.yaml a session reads

Beside the configuration reference, what an administrator needs from the config.yaml files every session reads, and the defaults and limits an organisation gives the machines of the people in it, from a plane or from a managed file.

Every session, on a pod or on a laptop, also reads settings from files and the TROUPE_* variables, merged by key and checked against one key table. The layers and every key are in docs/user/configuration.md; the schema is protocol/schema/config/v1.json. What an administrator needs from them:

  • A pod's provider is its profile's. The operator writes the provider, model and key into the pod as TROUPE_* (configuration A.3). A session on a pod never takes the keys that change approvals, endpoints and credentials, commands to run or readable paths from the project's own file; the rest of that file (models, budgets, the project brief) applies.
  • A file Troupe refuses fails the session's start, and says which file, which key and what to write: one that is not YAML, a value of the wrong type, an enum value nobody knows, both spellings of one setting, or a file written for a newer Troupe.
  • On a laptop, a workspace's files set those keys only once the workspace is trusted (trusted workspaces). The organisation's defaults sit below the user's file and what it enforces above everything (next section).
  • A repository can check its own file in CI: troupe config validate .troupe/config.yaml exits non-zero on any problem, an unknown key included.

Defaults and limits for people's machines

An organisation can give the laptops of the people in it defaults, which a person's own settings win over, and limits, which nothing on the machine goes past (Decision 869). Both are in one document, a defaults: section and an enforced: section, and it reaches a machine in one of two ways.

From a plane. The client defaults settings (configuration Part C) are the defaults: provider, URL, how the key is sent, and the three models. The key is each person's own: client_key_help is your word on where one comes from, a URL to the gateway's key page or "open a ticket at the helpdesk", shown by the terminal and the desktop app wherever a key is asked for. An organisation that would rather hand one key to everybody stores it as client_key, a secret the console never shows again; it rides the defaults as api_key, below each person's own file, and anybody who can sign in can read it. client_enforced is the enforced set, a JSON object such as {"approvals": "deny", "max_turns": 100}, set on the console's Organisation screen or with admin.setting.put, audited like every setting. The plane answers both in me.client_defaults (as defaults and enforced, beside the fields older clients read). A signed-in machine's daemon fetches it whenever a client connects with a plane token, keeps a copy in its state directory (organisation.json, with which plane and when), and uses that copy as it is while the plane cannot be reached; troupe config pull fetches it at once. The copy is the person's own file, so it is a default the person is held to, not a lock against them: see below.

From a managed file, for an organisation without a plane: one file at a fixed path, which no variable or flag moves.

System Path
Windows %ProgramData%\troupe\managed.yaml, on the system drive (read from the registry, not from the variable)
macOS /Library/Application Support/troupe/managed.yaml
Linux and others /etc/troupe/managed.yaml

Write it so only an administrator can change it. Its format:

version: 1
defaults:
  provider: openai
  base_url: https://llm-gw.example.com/v1
  auth: bearer
  api_key: "{env:ORG_GATEWAY_KEY}"
  models:
    default: glm-5.2
    cheap: qwen3.6-35b
enforced:
  approvals: deny
  base_url: https://llm-gw.example.com/v1
  max_turns: 100
  wall_clock_ms: 3600000
  permissions:
    deny: ["shell(git push --force)", "read_file(~/.ssh/**)"]
    ask: ["mcp(tracker)"]

defaults: takes any key a user's config.yaml takes except trusted_workspaces, and is checked the same way: a value of the wrong type refuses every session's start, naming the file and the line, and an unknown key warns. enforced: takes only these, each a ceiling:

Key Enforced, a machine may
max_tokens, max_turns, wall_clock_ms, max_depth set a lower number, not a higher one
approvals tighten wait to deny, not loosen deny
managed_mcp_servers_only, managed_permission_rules_only turn one on, not turn it off
provider, base_url nothing else: the session's provider is this one, and a named provider of another type or at another URL is refused
permissions add rules of its own, not loosen these: every file's per-tool rules are added together and the strictest that matches a call holds, so an enforced ask beats a person's allow (per-tool rules)

A rule under defaults: is added and holds the same way, since no rule is a default a person's file replaces; the two differ for rules only in how --explain names them (org and enforced), and managed_permission_rules_only keeps both. On a plane, client_enforced takes them as {"permissions": {"deny": ["shell(git push --force)"]}}, each checked when set; the console's Organisation page edits them as rules (a tool and a pattern, checked as typed) rather than JSON.

Any other key under enforced: is not enforced and warns, with the list; the plane refuses it when it is set. An enforced value is written out in full: {env:VAR} is refused there, since a person sets their own environment. troupe config validate managed.yaml checks a draft before it is put in place.

Both. Where a machine has both, the plane's defaults win over the file's, the stricter of two limits on one key holds, and a provider or URL both fix is the managed file's, with a warning: the managed file is the one a person cannot change.

What a person sees, and what a ceiling bounds (the question a session asks at an enforced max_turns or wall_clock_ms, and the room an enforced max_tokens leaves a model's thinking), are on the user's page: your organisation's defaults and limits.

What it is not. It is the organisation's word honoured by Troupe on the machine, not a control a person cannot get round on a machine they administer: the plane's copy is in their own state directory, and they choose which build they run. A managed file an administrator owns, on a machine its person does not administer, is the strong form.