Configuration

Wayland Core reads its configuration from a TOML file. Settings merge across three levels, each overriding the one above, so you can set a sane global default and adjust per project or per command.

The three levels

Configuration is resolved in this order, lowest priority first:

Global config file: applies everywhere. Run wayland-core --config-path to see where it lives on your OS.
Project file: a .wayland-core.toml in the working directory (or the directory passed with --project-dir). Overrides the global file for that project.
CLI flags and environment variables: the highest priority. A flag like --model wins over both files for that one run.

Generate a starting file with wayland-core --init-config.

A worked example

[default]
provider = "anthropic"
max_tokens = 8192
max_turns = 30

[providers.anthropic]
# api_key = "sk-ant-xxx"   # or set ANTHROPIC_API_KEY in the environment

[profiles.deepseek]
provider = "openai"
model = "deepseek-chat"
api_key = "sk-xxx"
base_url = "https://api.deepseek.com"

[profiles.ollama]
provider = "openai"
model = "qwen2.5:32b"
base_url = "http://localhost:11434/v1"

[mcp.servers.time]
command = "mcp-server-time"
args = ["--local-timezone", "UTC"]

Switch to a profile at run time:

wayland-core --profile deepseek "Summarize this repo"

Key sections

Section	What it controls
`[default]`	Default provider, model, `max_tokens`, `max_turns`, and other run defaults.
`[providers.*]`	Per-provider credentials and a `.compat` block for ProviderCompat quirks.
`[profiles.*]`	Named profiles you select with `--profile`; support `extends` for inheritance.
`[tools]`	Tool behavior, including auto-approve and allow-list settings.
`[session]`	Session persistence, storage directory, and `max_sessions`.
`[compact]`	Context compaction behavior.
`[file_cache]`	The file state cache (read deduplication, write tracking).
`[plan]`	Plan mode (`enabled`, `plan_directory`).
`[mcp.servers.*]`	MCP servers to connect, with transport, `command`/`args` or `url`, env, and `deferred`.
`[observability]`	Observability options, including `online_evolution`.

Profiles and inheritance

Profiles are the fast way to switch providers and models. A profile can pull settings from another with extends, so you keep shared values in one place and override only what differs. This is how you keep, for example, a fast and a deep profile that share everything but the model.

Environment variables

The engine reads PROVIDER, API_KEY, BASE_URL, and MODEL, along with provider-native keys such as ANTHROPIC_API_KEY and OPENAI_API_KEY. It also honors WAYLAND_HOME for its data directory and RUST_LOG for log verbosity. Environment variables sit above the config files and below explicit CLI flags in precedence.