Provider overview

How Cerevisor connects to models, provider types, the library, resolution order, and per-agent overrides.

The six provider types

Type What it is Authentication Cost model
Anthropic Direct API to Claude (Opus, Sonnet, Haiku). Cerevisor owns the agent loop. API key. Per token.
Gemini Direct API to Google's Gemini models (2.5 / 3.x families). Cerevisor owns the agent loop. API key from Google AI Studio. Per token, with a >200K input-tier bump on Pro models.
Claude Agent SDK Anthropic's official agent SDK (Claude Code's harness) running in-process. Delegated loop. Anthropic API key (separate keychain slot from the Anthropic provider). Per token, billed via your Anthropic account.
OpenAI-compatible Any endpoint speaking the OpenAI Chat Completions API. API key (or none, for Ollama). Per token, or free (local).
OpenAI Codex CLI Sidecar to OpenAI's codex command-line tool. Delegated loop. Device auth against your ChatGPT account. Subscription quota.
Cursor Agent In-process Cursor SDK runtime. Delegated loop. Cursor API key. Subscription.

Anthropic, Gemini, Claude Agent SDK, Codex CLI, and Cursor Agent are singletons: one entry per type. OpenAI-compatible allows N entries, so you can have OpenAI + Ollama + OpenRouter side by side as separate library entries.

Cerevisor-loop vs. delegated-loop providers. Anthropic, Gemini, and OpenAI-compatible give Cerevisor full control of the agent loop, which means per-tool permission prompts, mid-run pause/resume, skill injection, and contract retries all work. Claude Agent SDK, Codex CLI, and Cursor Agent hand the loop to the upstream runtime; you trade those Cerevisor-side features for the upstream harness's own behavior.

The Provider Library

All your credentials live in the Provider Library, accessed via Settings → Providers.

Each entry has:

  • A name (auto-generated from type + base URL, editable).
  • The provider type.
  • Connection details (base URL, model defaults).
  • A "default" badge: exactly one entry is the default at any time.

API keys are stored in the OS keychain. They're never written to a .cerevisor file and never logged.

Provider resolution

When an agent runs, Cerevisor resolves which provider to use via this chain:

  1. Agent-level override. If agent.providerId is set, use that.
  2. Workflow-level override. Else, if workflow.settings.providerId is set, use that.
  3. Library default. Else, use the library's default-marked entry.
  4. Fallback. Else, the first enabled credential.

This means a workflow can run mixed providers (different agents use different providers) without you having to configure them per workflow.

The default

One library entry is always marked default. New workflows use it. Agents in those workflows inherit it unless you override.

Change the default in Settings → Providers → Set as default on the entry you want.

What background features use the default

Cerevisor has a few features that use the default provider quietly in the background:

  • Chat builder: uses the default unless overridden in Settings → Chat Builder.
  • Run retrospectives: at end-of-run, the harness summarizes the run for memory storage. Uses the default.
  • Meta-cognition enrichment: periodic summary of what the harness has learned about you. Uses the default.
  • Skill summarization: the LLM-rich descriptions of skills (the upgrade pass). Uses the default.
  • Memory crystallization: periodic distillation of your freeform memory entries.

Codex CLI, Cursor Agent, and Claude Agent SDK are not valid background-feature providers. They don't expose a direct chat surface. If your default is one of those, you'll see "background feature unavailable" toasts. Configure a separate Cerevisor-loop provider (Anthropic, Gemini, or OpenAI-compatible) for background use via Settings, or live without the background features.

Workflow execution vs. background features

The provider system is split into two paths:

Path Routing
Workflow execution Per-agent resolution. Mixed providers OK. All six types OK.
Background features Always the default. Only Cerevisor-loop providers allowed (Anthropic, Gemini, OpenAI-compatible).

This is important because it lets you build a workflow where, say, every agent runs on Codex or Claude Agent SDK (subscription billed, or full Claude Code harness) while the chat builder runs on Anthropic Haiku or Gemini Flash (so you can still naturally edit workflows).

Where to go next

Back to docs