Configure models and providers

Cengrid is vendor-neutral. The agent loop runs on Pi, which drives models from several vendors, so switching models is configuration, not code. You choose which providers are enabled, which model is the default, and who can pick what.

Providers

Provider id	What it is	Key
anthropic	Anthropic’s Claude models	ANTHROPIC_API_KEY
openai	OpenAI models	OPENAI_API_KEY
openrouter	OpenRouter, a gateway to many vendors’ models	OPENROUTER_API_KEY
your own	Any service that speaks the OpenAI Chat Completions or Anthropic Messages protocol	Set per custom provider

Models are written as a bare id for Anthropic and OpenAI (for example claude-opus-5) and as vendor/model for OpenRouter catalog models. The built-in registry currently includes Claude Fable 5, Opus 5, Opus 4.8, Sonnet 5 and Haiku 4.5, three OpenAI GPT-5.6 models, and openrouter/auto. The picker in Governance → Models shows exactly what your deployment can serve.

Each provider has a default model: claude-opus-5 for Anthropic, gpt-5.6-sol for OpenAI and openrouter/auto for OpenRouter.

Add a provider key

You can supply a key at deploy time or later in the console.

Admin console

Open Admin → Onboarding → Model providers, then Add key, Replace key or Remove for each provider. Cengrid validates the key against the provider before saving, and stores it encrypted. A key saved here beats the one in the environment. Remove appears only for keys saved in the console. It disables the provider and masks the environment key.

Deployment config

Set modelProvider in cengrid.config.jsonc to anthropic, openai or openrouter. That makes the provider’s key a required secret. Put the key in .env and run cengrid secrets push. Optionally set model to choose the default model. Omit modelProvider entirely to add a key from the console after first boot.

{
  "modelProvider": "anthropic",
  "model": "claude-opus-5"
}

Use an API key, not a subscription token

An Anthropic subscription token (one starting sk-ant-oat) in ANTHROPIC_API_KEY is refused at boot. Use a Console API key.

cengrid doctor probes the configured provider with its key, and cengrid init --model-provider sets the provider for a new deployment (default anthropic).

Choose the base model

The base model is the model conversations run on. Set it in Governance → Models → Base model. The same setting exists for a team (Teams → Instructions and model) and for a person (their user page), and an empty value clears the override and goes back to inheriting.

For each turn, Cengrid picks the first of these that applies:

1. The model requested for that turn, if the person is allowed to choose one
2. The person’s base model
3. The team’s base model
4. The organisation’s base model
5. The deployment default (PI_MODEL, or the provider’s default)

The picker only offers models whose provider has a key. Saving a model that cannot be served on your deployment is rejected.

Which models people can pick

Governance → Models → Web UI models is the list people see in the web chat model picker. Set it for the organisation or a team. A team’s list narrows the organisation’s, by intersection, and an empty intersection falls back to the organisation’s list. With nothing set, the picker offers everything your deployment can serve. There is no separate deny list: a web turn is refused if its model is not enabled or its provider is not configured.

Model settings

Setting	Where	Meaning
Base model parameters	Governance → Models	Extra provider request fields as JSON, such as {"top_p": 0.9}. temperature and max_tokens are rejected here. Set those per agent.
Reasoning effort	Per turn, and stored per scope by the web runtime config	auto, low, medium, high, xhigh, max or ultracode. The default is low on Anthropic models and auto elsewhere, and triggered or scheduled turns default to xhigh. There is no Governance field for it. A depth the turn sets itself overrides effort keys in base model parameters.
Interactive fast mode	Governance → Models	An organisation flag for faster output on the models that support it: Claude Opus 5, 4.8, 4.7 and 4.6. Opus 4.7 and 4.6 resolve but are not offered in pickers.
Model spend limit (USD)	Governance → Advanced	A spend cap. The older BUDGET_USD_PER_WINDOW environment variables are ignored.

Individual model auth

Governance → Security → Individual model auth lets each person connect their own Anthropic or OpenAI key instead of using the organisation’s. When it is on, per-turn model and harness requests are ignored.

Add your own endpoint

A custom provider connects any OpenAI-compatible or Anthropic-compatible service: a self-hosted model server, a gateway or a proxy.

1. Open Admin → Onboarding → Custom model providers and choose Add provider. The dialog is titled “Add a custom model provider”.
2. Set the provider id, a slug of 2 to 32 lowercase letters, digits or hyphens starting with a letter, and a display name (up to 100 characters). The id cannot be anthropic, openai, openrouter or mock.
3. Choose the API format, OpenAI-compatible (Chat Completions) or Anthropic-compatible (Messages), and enter the base URL and API key. For the openai protocol the base URL includes /v1. For anthropic it does not.
4. Add 1 to 200 models, each with an id, an optional name (it defaults to the id), contextWindow (default 128000), maxTokens (default 8192) and input and output prices in USD per million tokens (default 0).
5. Save. Cengrid validates the key by calling the provider’s /models endpoint, unless you turn validation off.

Custom models are treated as non-reasoning and text-only. A model id cannot match a built-in model or one already served by another provider. Changing the base URL or protocol means entering the key again.

To send a built-in provider through a proxy instead, set ANTHROPIC_BASE_URL, OPENAI_BASE_URL or OPENROUTER_BASE_URL in env.core. They must be http(s) URLs with no credentials, query or fragment. cengrid doctor and the OpenRouter catalogue fetch use fixed URLs and ignore these overrides.

Helper models

Some work runs on a smaller model than the conversation:

Setting	Used for	Default
PI_TITLE_MODEL	Titles and approval summaries	The provider’s auxiliary model
PI_DETECT_MODEL	Deciding whether to respond, and the model-based security screen	The provider’s auxiliary model
COORDINATOR_MODEL	The coordinator	The conversation’s model

The default auxiliary model is claude-haiku-4-5 for Anthropic and gpt-5.6-luna for OpenAI, and otherwise the base model itself. Context compaction runs on the deployment default model (PI_MODEL, or the provider default), not on a person’s, team’s or organisation’s base model.

Environment variables

Variable	Meaning
HARNESS	pi runs real models. mock gives canned replies with no model calls, for tests. Core defaults to mock when unset, and the CLI scaffolds pi.
MODEL_PROVIDER	The active provider, validated against the harness.
PI_MODEL	The deployment default model.
ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY	Provider keys.
ANTHROPIC_BASE_URL, OPENAI_BASE_URL, OPENROUTER_BASE_URL	Redirect a built-in provider to a proxy.
HARNESS_SECURITY_POSTURE	unrestricted, auto (default) or strict. See security postures.

Model requests fetch the OpenRouter catalogue only when an OpenRouter key is configured. The catalogue is cached for five minutes.

Note

Google Gemini, AWS Bedrock, Vertex AI and Azure OpenAI have no native provider. If one of them offers an OpenAI- or Anthropic-compatible endpoint, add it as a custom provider.