Configuration

Three sources, each overriding the last. Layering is field by field.

The cascade

  1. ~/.config/cortex/config.yaml — your defaults (honours XDG_CONFIG_HOME)
  2. ./cortex.yaml — this project's overrides
  3. the environment — LLM_PROVIDER, LLM_MODEL

Layering is field by field, so a project config that names only a model keeps the provider from your user config. You only specify what you want to override.

⚠️
Specifying --config disables the cascade entirely — only that file is read, plus the environment. Use it when you want a specific, self-contained config.

The full file

name: reviewer                  # shown in the banner

provider: openrouter            # the axon provider name
model: deepseek/deepseek-v3.2   # the model within that provider

system_prompt: ./reviewer.md    # a path is read from disk; prose is used as written

pruner:                         # optional secondary model for context pruning
  model: meta-llama/llama-3.1-8b
  provider: openrouter          # defaults to the main provider if omitted

mcp_servers:                    # spawned at startup, their tools auto-discovered
  github:
    command: docker
    args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"]
    env: ["GITHUB_TOKEN=..."]

Providers and credentials are not in this file

cortex's config only names which provider and model to use. Endpoints and credentials live in axon's config — the shared providers.json the axon-family tools already use, or the LLM_API_KEY / LLM_BASE_URL environment variables. SeeAPI keys for the resolution order.

Known providers

provider supplies base_url for openai,openrouter, anthropic, groq, deepseekand ollama. Any other provider must state its own base_url(via axon's config or LLM_BASE_URL). A localhost endpoint (e.g. ollama) needs no API key.

System prompt

Omit system_prompt and cortex uses its built-in coding-agent role text. The tool catalog is appended by axon, so a custom prompt must not enumerate tools— or you pay for those tokens twice on every call. SeeArchitecture for why.

The fastest possible start

export LLM_MODEL=gpt-4o
export LLM_API_KEY=sk-...
cortex