Skip to content

Configure Your Model (Bring Your Own Keys)

In plain English

CortexBuild is model-agnostic and bring-your-own-keys. It never marks up tokens, never stores your keys, and LLM use is opt-in and off by default. Most of the pipeline runs with no model at all.

Pre-alpha

cortexbuild-core is 0.0.1 (Phase 0). If you haven't installed the CLI yet, do the dev install first.

Do you even need a model?

The core CortexBuild workflow is deterministic, offline, and free — no LLM required:

Command What it does Needs a model?
cortexbuild init run . Brownfield onboarding (Passes 1–4) No
cortexbuild render Render rules into your AI tools No
cortexbuild render --check CI drift gate No
cortexbuild eval Offline conformance scoring No
cortexbuild conformance Maturity report No
cortexbuild feedback Deterministic feedback synthesis No
cortexbuild debt-heatmap Technical-debt heatmap No
cortexbuild ledger … Recurrence-ledger management No

A model is only needed for the opt-in LLM steps:

  • cortexbuild init run --with-rule-synthesis (convention inference)
  • cortexbuild synthesize-rules (standalone rule synthesis)
  • The LLM-assisted review agent roles (Critic, Security, etc.) when invoked via the orchestrator

If you only use the deterministic path, stop here — you're done.

Turn on LLM features

LLM features are gated behind an environment variable. Set it before running any LLM-dependent command:

export CORTEXBUILD_LLM=1

$env:CORTEXBUILD_LLM = "1"

Without this variable, LLM code paths are never reached — even if a provider is configured.

Native providers

CortexBuild ships two native provider adapters:

Anthropic (default preference)

pip install -e ".[anthropic]"

Provide your API key via the provider's standard environment variable (see Provider Adapter for the full interface). Anthropic is the first-preference provider in the default routing table.

Google Gemini

pip install -e ".[gemini]"

Provide your API key via the provider's standard environment variable. See Provider Adapter for configuration details.

Both adapters support the ModelTier system (reasoning_heavy, balanced, fast_cheap) so CortexBuild can route tasks to the right cost/capability tier automatically.

Any other model via an OpenAI-compatible endpoint

Everything beyond the two native adapters — including local / self-hosted models and cloud gateways — is reached through a single OpenAI-compatible base_url seam.

Install the OpenAI-compatible extra:

pip install -e ".[llm]"

Then create .cortexbuild/llm-config.yaml in your repo:

# .cortexbuild/llm-config.yaml
schema_version: 1
provider: ollama
model: llama3
base_url: http://localhost:11434/v1
api_key_env: OLLAMA_API_KEY
locality: local

Key fields:

Field Purpose
schema_version Always 1 (current).
provider A human-readable label (e.g. ollama, vllm, lm-studio, bedrock-proxy).
model The model name your endpoint expects.
base_url The OpenAI-compatible endpoint URL.
api_key_env Name of the environment variable holding the API key. Never put a raw key in this file — inline secrets are rejected at parse time (fail-closed). A keyless local endpoint may omit this field.
locality local (loopback, no bytes leave the machine), self_hosted_lan (operator-controlled LAN host — off-box), or cloud. Recorded as data; the egress redaction choke-point wraps every endpoint regardless.

Local / self-hosted models

Any server that exposes an OpenAI-compatible /v1/chat/completions endpoint works:

Server Typical base_url
Ollama http://localhost:11434/v1
vLLM http://localhost:8000/v1
LM Studio http://localhost:1234/v1
text-generation-inference http://localhost:8080/v1

Set locality: local for on-box servers (zero egress) or locality: self_hosted_lan for a LAN-hosted GPU server.

Cloud gateways (Bedrock, Vertex, Azure OpenAI)

There is no native AWS Bedrock, Google Vertex, or Azure OpenAI adapter today. These clouds are reachable through an OpenAI-compatible proxy (e.g. LiteLLM, a Bedrock-to-OpenAI shim, or the provider's own compatibility endpoint):

schema_version: 1
provider: bedrock-proxy
model: anthropic.claude-sonnet-4-20250514
base_url: http://localhost:4000/v1
api_key_env: LITELLM_API_KEY
locality: cloud

Set locality: cloud so the system records that bytes leave your network.

Picking the right model per task (cost optimisation)

CortexBuild's Provider Adapter defines three model tiers:

Tier Best for Example models
reasoning_heavy Planner, Critic, Security, PR Reviewer — high-risk reasoning Claude Opus, GPT-5
balanced Builder, Optimizer — most volume, cost matters Claude Sonnet, GPT-5-mini
fast_cheap Tester, Explore — pattern-checking, read-only summarisation Claude Haiku, GPT-5-nano

The recommended operating pattern:

  1. Use cheaper / local models for narrow, low-risk, deterministic-adjacent steps (test generation, exploration, documentation drafts).
  2. Use stronger cloud models for Critic, Security Compliance, and other high-risk reasoning roles.
  3. Validate outputs with the deterministic gates (eval, conformance, render --check) — these are free and catch regressions regardless of which model produced the change.
  4. Fall back to a stronger model when a cheaper model's output fails validation.

You can override the default tier routing per project and per agent. See Provider Adapter — Per-agent default routing for the routing table.

Privacy & egress

Your keys are yours, by-reference only (environment variables), and are never persisted or logged by CortexBuild. The system is offline by default — nothing leaves your machine unless you explicitly opt into an LLM call or an explicit egress action. Every LLM endpoint (including local ones) is wrapped by the egress redaction choke-point, which scrubs sensitive tokens before any request is sent.

Next