Config File Reference (TOML)

Wayland Core reads a TOML config file that merges in three levels: the global file first, then a project .wayland-core.toml in the working directory, then CLI flags and environment variables. Later levels override earlier ones. Generate a starter file with wayland-core --init-config and find its path with wayland-core --config-path.

This page lists every section. A minimal config sets only [default] and one provider.

A complete example

[default]
provider = "anthropic"
# model = "claude-sonnet-4-20250514"
max_tokens = 8192
max_turns = 30

[providers.anthropic]
# api_key = "sk-ant-xxx"       # or env var ANTHROPIC_API_KEY
# base_url = "https://api.anthropic.com"

[providers.openai]
# api_key = "sk-xxx"           # or env var OPENAI_API_KEY
# base_url = "https://api.openai.com"

# A custom alias over a built-in provider
[providers.my-service]
provider = "openai"
model = "custom-model-v1"
api_key = "sk-xxx"
base_url = "https://my-service.example.com/api/openai"

# Named profiles, switched with --profile <name>
[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"
api_key = "ollama"
base_url = "http://localhost:11434"

[tools]
auto_approve = false
allow_list = ["Read", "Grep", "Glob"]

[session]
enabled = true
# Defaults to a per-user absolute path: <config-dir>/wayland-core/sessions
# Set an explicit path only to override that default.
max_sessions = 20

[compact]
compaction = "safe"   # off | safe | full
toon = false

[file_cache]
enabled = true
max_entries = 100

[plan]
enabled = true
plan_directory = ".wayland-core/plans"

Sections

[default]

The base run settings.

Key	Description
provider	Provider name or a config alias, for example anthropic.
model	Default model id.
max_tokens	Max output tokens per response.
max_turns	Max agent loop turns.

[providers.<name>]

One block per provider. For built-in providers, set api_key and optionally base_url. To define an alias over a built-in, set provider to the underlying built-in name (anthropic, openai, bedrock, or vertex) and override model, api_key, base_url, or compat.

Key	Description
provider	For an alias: the underlying built-in provider.
api_key	API key for the provider.
base_url	API base URL (used by OpenAI-compatible providers).
model	Default model for this provider entry.
compat	A sub-table tuning request shaping for OpenAI-compatible backends.

[profiles.<name>]

Named bundles of provider, model, and credential settings, selected with --profile. A profile can set extends = "<other-profile>" to inherit from another profile, and mcp_servers = ["..."] to scope which MCP servers it uses. Child values override the parent.

[tools]

Key	Default	Description
auto_approve	false	Approve all tool calls without prompting.
allow_list	Read-only defaults (see below)	Tool names that are always allowed. Defaults to a built-in read-only set: ["Read", "Grep", "Glob", "web", "WebFetch", "vision_analyze", "transcribe_audio", "ToolSearch", "Skill", "wayland_status", "wayland_telemetry_query"].

[session]

Key	Default	Description
enabled	true	Save sessions for later resume.
directory	<config-dir>/wayland-core/sessions	Where session files are stored. Defaults to a per-user absolute path under the engine config dir (honors $WAYLAND_HOME), not a path relative to the project.
max_sessions	20	How many sessions to keep.

[compact]

Key	Default	Description
compaction	safe	Output compaction level: off, safe, or full.
toon	false	Encode JSON arrays with TOON.

[file_cache]

Key	Default	Description
enabled	true	Cache file reads and track writes.
max_entries	100	Max cached files (LRU).

[plan]

Key	Default	Description
enabled	true	Allow plan mode.
plan_directory	.wayland-core/plans	Where plans are written.

[mcp.servers.<name>]

One block per MCP server. Set the transport and its address, plus any args, environment, or headers. Mark a server deferred = true so its tool schemas load on demand. See MCP Client.

[observability]

Set online_evolution = true to enable live online evolution, the config equivalent of the --online-evolution flag.

Next

• Environment Variables
• CLI Flag Reference
• Configuration