Configuration and Models¶

Codaris uses two kinds of model. A local decision model (Primeomicx/nf-pilot) answers small, fixed questions in milliseconds: what kind of request a turn is, what category a failure falls into, which of several candidate tools or layouts fits. A language model, cloud or local, writes the plan, the code, and the repairs. This page covers the keys, the routing, and the state directory.

1. Provider keys¶

Add keys under Customizations in the web studio. Each key is checked against its provider before it is saved, and the saved value goes to ~/.codaris/settings.json (secrets are stored there and never returned to the browser in plain text). The same variables work from the environment or from backend/.env:

export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIzaSy..."
export PERPLEXITY_API_KEY="pplx-..."

A provider counts as configured when its key is present. The routing below only resolves to models whose provider is configured, so one key is enough to start, and adding a second provider widens the choice without any other change.

2. Model identifiers¶

Models are named provider:model. The catalog groups them into three tiers, and each task in the engine asks for a tier rather than a specific model:

Perplexity also routes the OpenAI, Anthropic, and Google models through one key (perplexity:openai/gpt-5.6-terra, perplexity:anthropic/claude-sonnet-5, and so on). GET /api/models lists the catalog with the tier each entry belongs to and the model the current keys resolve each tier to.

Any provider:model string is accepted for a provider in the catalog, and an unknown prefix (my-gateway:some-model) is passed through unchanged for gateways that expose an OpenAI-compatible endpoint.

3. Routing¶

Three settings pin a model for a role. Each is a field under Customizations and an environment variable:

A setting is honoured when its provider is configured. When the key behind a saved setting is removed, the setting is skipped with a warning in the backend log, the Customizations page shows the model the role resolves to instead, and a chat turn that names such a model gets a note in the transcript naming the key it needs and the model used for that turn. The composer's Auto, Fast, and Deep choices map to the default, digest, and build models respectively.

Two more variables cover narrower roles: CODARIS_JUDGE_MODEL pins the judge (cheap tier when unset), and CODARIS_DEBUG_MODEL names the model a /run turn uses for failure analysis (unset by default, so run turns follow the chat model). CODARIS_FORCE_BUILD_MODEL=1 and CODARIS_FORCE_DEBUG_MODEL=1 make those two overrides hard pins instead of defaults that an explicit model choice in the composer can replace.

4. Local models¶

Any server with an OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, llama.cpp) is a provider called local-api. Set the base URL under Customizations or in the environment, and name the model after the prefix:

export CODARIS_LOCAL_LLM_BASE_URL="http://localhost:11434/v1"   # the default
export CODARIS_LOCAL_LLM_API_KEY="not-needed"                   # when the server requires one
export CODARIS_DEFAULT_MODEL="local-api:qwen2.5-coder:32b"

From inside the Docker image the host is host.docker.internal, so the base URL becomes http://host.docker.internal:11434/v1. local-api counts as configured whenever a base URL is set, and the resolver falls back to it when no cloud key is present, so a fresh install with Ollama running on the default port works without a key.

An Anthropic-compatible local endpoint uses CODARIS_LOCAL_ANTHROPIC_BASE_URL, CODARIS_LOCAL_ANTHROPIC_API_KEY, and the local-anthropic: prefix.

5. The decision model (nf-pilot)¶

The image ships the weights, so the decision model runs without network access. GET /health reports its status, the device, and the measured average latency over the calls made since the backend started (avg_latency_ms is null until the first call).

6. The state directory¶

Everything Codaris keeps lives in one directory: settings.json (keys and routing), the chat database, runs.db, the unpacked test-asset cache, MCP server definitions (mcp_servers.json), and session workspaces. The versioned stores themselves sit beside the code (backend/app/engine/, baked into the image).

The environment variables reference lists the remaining variables, grouped by what they switch.