Config file reference

Every field in a cortex config file, what it means and what it overrides.

Locations

Source	Path	Notes
User config	`~/.config/cortex/config.yaml`	Honours `XDG_CONFIG_HOME`
Project config	`./cortex.yaml`	Overrides user config, field by field
Environment	`LLM_*`	Overrides both
Explicit	`--config <path>`	Disables the cascade entirely

Fields

Field	Type	Description
`name`	string	Labels this agent personality (e.g. `cortex`, `reviewer`). Shown in the banner.
`provider`	string	The axon provider name (e.g. `openai`, `openrouter`). Supplies a default `base_url` for known providers.
`model`	string	The model within that provider (e.g. `gpt-4o`, `deepseek/deepseek-v3.2`).
`system_prompt`	string	The agent's role text. A path is read from disk; prose is used as written. Omit to use the built-in coding-agent prompt. Must not enumerate tools — axon appends the catalog.
`pruner`	object	The secondary model for context pruning. See below.
`mcp_servers`	map	MCP subprocesses to spawn at startup. See below.

`pruner`

Field	Type	Description
`pruner.provider`	string	Provider for the pruner model. Defaults to the main provider if omitted.
`pruner.model`	string	The cheap, fast model used for context pruning. Empty means no pruner.

`mcp_servers`

Each key is a server name. Each value has:

Field	Type	Description
`command`	string	The executable to spawn.
`args`	[]string	Arguments passed to the command.
`env`	[]string	Environment variables for the spawned process. Literal values — no `$` expansion.

Environment overrides

Only model selection is overridable by the environment. Credentials and endpoints are axon's concern.

Variable	Overrides
`LLM_PROVIDER`	`provider`
`LLM_MODEL`	`model`
`LLM_BASE_URL`	The provider's default `base_url`
`LLM_API_KEY`	API key (see API keys)

⚠️

Providers and credentials are not in this file. cortex does not define endpoints or carry credentials — those live in axon's providers.json or theLLM_* environment. cortex only names which provider and model to use.