Credentials

Comma-agents uses a layered credential system to resolve API keys and other secrets for AI providers. Credentials can come from environment variables, a persisted credentials file, or both — with a clear priority chain that lets you override per-strategy.

Credential types

Every credential is one of three shapes:

ApiCredential

OAuthCredential

CustomCredential

Resolution chain

When an agent needs credentials for a provider (e.g. openai), the credential store checks three sources in order, returning the first match:

1. Strategy-scoped credential — a credential saved for a specific strategy name
2. Environment variable — the well-known env var for that provider (e.g. OPENAI_API_KEY)
3. Global credential — a credential saved under the $global scope

If none of the three sources have a credential, the resolution returns undefined and model creation will fail.

resolve("openai", "my-strategy")
│
├─ 1. Check credentials["my-strategy"]["openai"]  →  found? return it
├─ 2. Check $OPENAI_API_KEY env var               →  set?   return { type: "api", key: value }
└─ 3. Check credentials["$global"]["openai"]      →  found? return it
                                                      else   undefined

Environment variables are always synthesized into ApiCredential objects ({ type: "api", key: value }). Empty string values are treated as absent.

Quick start

The fastest way to provide credentials is to set environment variables:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

See Supported providers for the full list of recognized environment variables.

For persistent storage or per-strategy overrides, use the credential store with a storage backend.