A config file has one key table, is read strictly, and says where each value came from; a workspace's own files set the keys that decide what may run only once the workspace is trusted¶
Decision 686 · accepted · 2026-09-25 · issue #122
Troupe.Config.Schema is the table: every key's type, default, which files may set it,
whether it is a secret, and what it does. Troupe.Config.Layers reads and merges the
files against it, and mix troupe.config.schema writes protocol/schema/config/v1.json
and the key reference in docs/user/configuration.md from it, which CI checks with
--check.
- Version. version: 1; a file without it is version 1, and a higher one is
refused as written for a newer Troupe.
- Strict. A file that is not YAML, a value of the wrong type, or an enum value nobody
knows (provider, auth, approvals, a provider's type, an MCP server's
permission) refuses the load, naming the file, the line, the key and what to write;
session.create answers with that. Nothing loads as %{} and no enum falls back.
yes/no/on/off, which YAML 1.2 reads as words, are read as the booleans they mean
for a boolean key, with a warning, and the approval gate takes only true as on.
Options a client or the command line passes are checked against the same table.
- Unknown keys warn, with the file, the line and the nearest key; x- keys pass and
land in extra. mouse and llm_timeout_ms are keys of their own, and
llm_timeout_ms is now the request's timeout.
- One spelling. models.{default,cheap,expensive,windows}, and api_key with auth:
bearer. model, small_model, expensive_model, windows, models.small and
auth_token load until version 2, each with a warning; both spellings of one setting in
one file refuse it. Every writer — the daemon's config.set and config.import, the
terminal UI's settings page, troupe config migrate --write — goes through
Troupe.Config.Migrate.write/2, which writes the new spellings, version: 1, a
yaml-language-server header naming the schema, and keeps the file it replaced as
.previous. Loading never rewrites a file, since a rewrite drops comments. troupe
config trust and untrust (#161) change one list and nothing else, so they edit the
file's own lines instead (Troupe.Config.Yaml.edit_list/4), keep .previous all the
same, and change nothing when the edit does not read back as that one change.
- Maps merge by key (RFC 7396): a map merges, null removes, a list replaces.
- {env:VAR} that is not set refuses the provider or MCP server that reads it, naming
the variable, and anywhere else refuses the load. A refused provider's target carries
{:refused, why} as its key, which both adapters answer with that error and no request.
ANTHROPIC_API_KEY and OPENAI_API_KEY are used only with the vendor's own endpoint
(Troupe.LLM.Endpoint.vendor?/2).
- Scopes and trust. A key is :any, :trusted or :user. The trusted keys change
approvals (auto_approve, approvals, the two managed_*), endpoints and credentials
(provider, base_url, api_key, auth, providers), commands to run (mcp), or
readable paths (read_roots, state_dir, fake_script). A workspace's
.troupe/config.yaml and config.local.yaml set them only when the workspace, or a
directory above it, is on trusted_workspaces in the user file, the one :user key;
otherwise they are ignored with a warning that names the command to trust it, troupe
config trust. A git worktree of a trusted checkout is trusted when the checkout's
.git/worktrees/<name>/gitdir names it back, and troupe config trust in a worktree
writes the checkout, which trusts them all. A session on a pod (kind: :team) resolves
with trust: :never.
- Precedence is unchanged, with .troupe/config.local.yaml between the project
file and the environment.
- Seeing it. troupe config --explain [KEY] [--json] shows every value, secrets
masked, with the layer and file that set it, and for one key its whole ladder,
ignored entries and why included. troupe config validate [PATH] exits 1 on any
error, refusal or warning. troupe config migrate [--write] [PATH] prints each
file's rewrite. troupe-daemon config takes the same arguments.
- Choices made here. The trust list is a list of paths in the user file, a directory
trusting what is under it, and not a per-workspace prompt, which #60 adds.
config.local.yaml is gated like the project file: it lives in the workspace, and
nothing but .gitignore keeps it out of a repository. The schema's $id, and the
header writers add, is https://troupe.dev/schema/config/v1.json, the protocol schema's
pattern; until it is served, an editor points at the file.
Governs: apps/troupe_core/lib/troupe/config.ex, apps/troupe_core/lib/troupe/config/model_settings.ex, apps/troupe_core/lib/troupe/config/settings.ex, apps/troupe_core/lib/troupe/mcp/local.ex, apps/troupe_core/lib/troupe/mcp/trust.ex, apps/troupe_core/lib/troupe/session.ex