Configuring an LLM

An LLM is optional. canonic’s answer path is fully deterministic and never calls one. It’s only used to draft semantics/knowledge during setup and reconciliation. The llm: block in canonic.yaml supports four providers, all behind the same interface.

openai_compatible
anthropic
openai
github_copilot

Local runtimes (Ollama, vLLM, LM Studio, llama.cpp, TGI) or any hosted OpenAI-compatible endpoint. base_url is required, and a key is optional (local servers typically need none):

llm:
  provider: openai_compatible
  base_url: http://127.0.0.1:11434/v1   # Ollama, swap for any OpenAI-compatible endpoint
  model: gemma-4-e2b-it-4bit
  api_key_ref: env:CANONIC_LLM_API_KEY   # optional

Claude, called directly. No base_url needed. api_key_ref is required:

llm:
  provider: anthropic
  model: claude-opus-4-8
  api_key_ref: env:ANTHROPIC_API_KEY

OpenAI’s hosted API directly (not a self-hosted/compatible endpoint). No base_url needed. api_key_ref is required:

llm:
  provider: openai
  model: gpt-4o
  api_key_ref: env:OPENAI_API_KEY

Routed through your GitHub Copilot subscription. No base_url, and no api_key_ref: authentication is a one-time device-code flow (a browser prompt on first use), and the resulting credential is cached on disk and reused after that:

llm:
  provider: github_copilot
  model: gpt-4.1

Structured/schema-constrained output (used for drafting) isn’t honored by every model Copilot proxies. Claude and most GPT models silently return prose instead of JSON. Stick to a model litellm marks as schema-capable for this provider (gpt-4.1, gpt-5, gpt-5.1, gpt-5.2) if you hit structured_output_unsupported.

One interface, any provider

All four are reached through litellm behind one interface, with no per-provider branching anywhere else in canonic. tasks: optionally overrides the model per task (draft, reconcile):

llm:
  provider: anthropic
  model: claude-haiku-4-5
  api_key_ref: env:ANTHROPIC_API_KEY
  tasks:
    reconcile: claude-opus-4-8   # a harder task gets a stronger model

Air-gapped mode

Under runtime.air_gapped: true, only a local endpoint (loopback, or an allowlisted host via runtime.allow_cidrs) is accepted. openai, anthropic, and github_copilot all call a fixed public endpoint and are rejected outright in that mode.

Getting Started

Concepts

CLI Reference

MCP / Agent Integration

Guides

Reference

Configuring an LLM

One interface, any provider

Air-gapped mode

​One interface, any provider

​Air-gapped mode

One interface, any provider

Air-gapped mode