Providers

Providers are the model backends Koda invokes during task execution. The current control plane has managed verification for Anthropic (Claude), OpenAI, Google (Gemini), Ollama, ElevenLabs, Perplexity, Mistral, Qwen, Kimi, Groq, DeepSeek, xAI, OpenRouter, and local model paths such as llama.cpp, MLX, Kokoro, and Whisper. Each connection is configured and verified through the control plane — credentials never live in per-agent .env files.

Connection lifecycle

Every provider goes through the same three-stage lifecycle. The dashboard reflects state at each stage; the API mirrors it.

1. 1

   Configure

   Paste credentials (API key, login session, local endpoint URL, optional base URL, or optional org/project identifiers depending on the provider) through the provider wizard in the dashboard, or PUT /api/control-plane/providers/:provider_id/connection/api-key. The control plane encrypts the credential at rest before it touches the database.
2. 2

   Verify

   Koda calls the provider's authenticated endpoint and surfaces the raw error on failure. A wrong scope reads differently from a revoked key from a billing block. You'll never save a credential that can't round-trip.
3. 3

   Set defaults

   Once verified, pick a default model where the provider requires one. Agents can override model choices per role, but defaults make agent creation predictable.

Supported providers

API surface

The provider endpoints share a consistent shape:

• GET /api/control-plane/connections/catalog — list every supported provider and integration.
• PUT /api/control-plane/providers/:provider_id/connection/api-key — save an API-key-based credential.
• PUT /api/control-plane/providers/:provider_id/connection/local — save a local-endpoint provider (Ollama).
• POST /api/control-plane/providers/:provider_id/connection/login/start — start supported provider login flows.
• POST /api/control-plane/providers/:provider_id/connection/verify — round-trip the credential against the provider's API.
• GET /api/control-plane/providers/ollama/models, /providers/embedding/models, /providers/whispercpp/models, and voice/model download routes — inspect and manage local model catalogs.

$curl -X PUT https://koda.example.com/api/control-plane/providers/anthropic/connection/api-key \
$  -H "Cookie: koda_operator_session=..." \
$  -H "Content-Type: application/json" \
$  -d '{"api_key": "sk-ant-..."}'

Fallback and resume

Koda records provider health and makes provider choice part of the agent configuration. Runtime fallback depends on the agent's configured model policy and available verified providers; do not assume fallback exists until a second usable provider is connected and allowed for that agent.

Per-agent model override

Agents can override the provider default. A common pattern: use a fast / cheap model for triage steps, then escalate to a larger model for the final draft. Overrides live on the agent definition, so they're versioned and audited along with the rest of the agent config.

Integration health

Connection status is inspectable through GET /api/control-plane/integrations/:integration_id/health. The dashboard surfaces recent health snapshots in the Operations view; if verification starts failing after a key rotation, you'll see it there before an agent fails mid-task.

Next steps

• Telegram — wire up the messenger interface and control who can reach it.
• Environment variables — bootstrap values that control provider behaviour.