Integrations

Providers

Connecting Anthropic, OpenAI, Google, and Ollama.

Providers are the model backends Koda invokes during task execution. Four are supported out of the box: Anthropic (Claude), OpenAI (GPT / Codex), Google (Gemini), and Ollama (local / self-hosted). Each 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.

Configure
Paste credentials (API key, optional base URL, optional org/project identifiers) 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.
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.
Set defaults
Once verified, pick a default model for the provider. Agents can override this per role, but the provider needs a default so agent creation can complete without extra guessing.

Supported providers

Provider	Auth	Good for
Anthropic	API key	Long-context reasoning, tool loops, default for planning and long-form generation.
OpenAI	API key (+ optional org, project)	Codex workflows, cost-sensitive tiers, strong code generation.
Google	API key	Multi-modal tasks, large context windows.
Ollama	Local endpoint URL	Self-hosted or on-prem models. No API key.

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/verify — round-trip the credential against the provider's API.

bash

$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

When a provider is unavailable or returns an error, the runtime can degrade to a smaller model or fall over to a peer provider. The tool loop is resumed on the new provider with the transcript and tool-loop context attached — so an agent that started on claude-opus can finish on claude-sonnet (or another provider entirely) without losing the work.

Configure multiple providers

Fallback only works if multiple providers are configured. Connecting at least two — ideally from different vendors — gives the runtime somewhere to go when the first one has a bad hour.

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.