config.toml and layers

Configuration is the setup. Whatever a command, a flow or the UI configures is a key in a config.toml, and writing that key by hand does exactly the same thing. There is no hidden state: the only things kept outside configuration are runtime state (OAuth tokens, sessions, trust answers).

#The layers

Settings come from five files, merged key by key. A closer layer wins, except where a managed value is a ceiling.

Command-line flags sit on top of all of them for one run.

• Managed is written by an administrator. Nothing below it can lift a managed deny, a managed consent or [registry] unpinned = "refuse".
• User is yours, in every project. Put providers and keys here.
• Workspace and project files are committed with the repository. They load only once you trust the workspace (Workspace trust). They may name a secret's variable ("$VAR"), never the secret.

#Ask where a value came from

orrery config explain providers.ollama.model

providers.ollama.model = "qwen3:4b" — user, C:\Users\you\.orrery\config.toml:5 — in force

Every key, the layer that set it, the file, the line, and whether it won. Run it whenever a setting seems not to apply.

#Write a key

orrery config set budget.maxTurns 40
orrery config set providers.groq.model llama-3.3-70b
orrery config set permissions.shell ask --layer workspace
orrery config unset budget.maxTurns

config set keeps the rest of the file as it is, comments included. The value is TOML (true, 42, ["a"]) or plain text. A value of the wrong type is refused and nothing is written. --layer is user (the default) or workspace.

#A starter file

orrery init

writes a commented .orrery/config.toml into the workspace with a starter [permissions] table. An empty file is also a valid configuration.

#Mistakes fail loudly

A misspelt key or a value of the wrong type fails at load with its file, its line and the keys that exist there:

`toolTimeoutMS` is not a budget field: expected one of maxTurns, maxTokens, wallClockMs, maxUsd, maxMicroUsd, toolTimeoutMs

#Import from another harness

orrery import             # lists the harnesses it can import from
orrery import --from <id>

#Every key

See Config keys.