Skip to content

Provider Keys

This is the active setup guide for configuring provider secrets in SecondBrain.

Purpose

  • keep provider credentials out of git and plaintext docs
  • make sb doctor, sb chat, and related commands use the right environment variables
  • document the current supported provider inputs

Use the helper scripts in the repo root:

scripts/sb-secrets set OPENAI_API_KEY "sk-..."
scripts/sb-secrets set ANTHROPIC_API_KEY "..."
scripts/sb-secrets set GOOGLE_API_KEY "..."
scripts/sb-secrets set GROQ_API_KEY "..."
scripts/sb-secrets set OPENROUTER_API_KEY "..."
scripts/sb-secrets set MISTRAL_API_KEY "..."
scripts/sb-secrets set DASHSCOPE_API_KEY "..."

# Optional default model overrides
scripts/sb-secrets set SB_OPENAI_MODEL "gpt-5.5"
scripts/sb-secrets set SB_ANTHROPIC_MODEL "claude-opus-4-7"
scripts/sb-secrets set SB_GEMINI_MODEL "gemini-3.1-pro-preview"
scripts/sb-secrets set SB_GROQ_MODEL "openai/gpt-oss-120b"
scripts/sb-secrets set SB_OPENROUTER_MODEL "openai/gpt-5.5"
scripts/sb-secrets set SB_MISTRAL_MODEL "mistral-medium-3-5"
scripts/sb-secrets set SB_QWEN_MODEL "qwen3-coder-plus"

# Optional OpenAI endpoint selection
scripts/sb-secrets set SB_OPENAI_API_REGION "us"
scripts/sb-secrets set SB_OPENAI_API_BASE "https://us.api.openai.com"
scripts/sb-secrets set OPENAI_PROJECT_ID "proj_..."

# Load the exported values into the current shell
eval "$(scripts/sb-secrets shell)"

Verify

sb doctor
sb providers health
sb chat --provider openai

If you are onboarding a new local setup, sb onboard is the best first command. It does not replace secret configuration, but it does make provider readiness visible earlier in the setup flow.

Current Provider Inputs

Provider Key / Config
OpenAI OPENAI_API_KEY, optional SB_OPENAI_MODEL, SB_OPENAI_API_REGION, SB_OPENAI_API_BASE, OPENAI_ORG_ID, OPENAI_PROJECT_ID, SB_OPENAI_MAX_RETRIES
Anthropic ANTHROPIC_API_KEY, optional SB_ANTHROPIC_MODEL, SB_ANTHROPIC_API_BASE
Gemini GOOGLE_API_KEY, optional SB_GEMINI_MODEL, SB_GEMINI_API_BASE
Azure OpenAI AZURE_API_KEY + SB_AZURE_API_BASE + deployment name in SB_AZURE_MODEL
Bedrock AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + optional AWS_SESSION_TOKEN + SB_BEDROCK_MODEL
Cohere COHERE_API_KEY
Groq GROQ_API_KEY
OpenRouter OPENROUTER_API_KEY
Mistral MISTRAL_API_KEY
Qwen DASHSCOPE_API_KEY, optional SB_QWEN_MODEL, SB_QWEN_API_BASE
xAI XAI_API_KEY
Cerebras CEREBRAS_API_KEY
Fireworks FIREWORKS_API_KEY
Nebius NEBIUS_API_KEY
Parasail PARASAIL_API_KEY
Perplexity PERPLEXITY_API_KEY
Replicate REPLICATE_API_TOKEN
Vertex AI ADC / GOOGLE_CLOUD_PROJECT or SB_VERTEX_PROJECT, plus SB_VERTEX_MODEL
vLLM / SGLang SB_VLLM_API_BASE / SB_SGL_API_BASE and SB_VLLM_MODEL / SB_SGL_MODEL
Ollama local host/model configuration, no cloud key required
Local no provider key required

Most providers use the same naming convention:

  • secret: <PROVIDER>_API_KEY
  • model override: SB_<PROVIDER>_MODEL
  • custom endpoint override: SB_<PROVIDER>_API_BASE

Additional model-selection variables such as SB_OPENAI_MODEL, SB_ANTHROPIC_MODEL, and SB_GEMINI_MODEL remain optional overrides rather than required secrets.

Built-in defaults are intentionally high-capability for sb chat: OpenAI gpt-5.5, Anthropic claude-opus-4-7, Gemini gemini-3.1-pro-preview, Groq openai/gpt-oss-120b, xAI grok-4.3, Cohere command-a-03-2025, Mistral mistral-medium-3-5, OpenRouter openai/gpt-5.5, Qwen qwen3-coder-plus, and the OSS-compatible hosted providers default to gpt-oss-120b variants where supported. Override these if your account, deployment, or budget requires a different model.

Qwen Cloud uses the OpenAI-compatible DashScope endpoint. SecondBrain defaults SB_QWEN_API_BASE to https://dashscope-intl.aliyuncs.com/compatible-mode and appends /v1 when calling chat completions or model discovery. You can also set SB_QWEN_API_BASE to the official full base URL ending in /v1.

OpenAI endpoint selection:

  • Leave SB_OPENAI_API_REGION unset, or set it to global, to use https://api.openai.com/v1.
  • Set SB_OPENAI_API_REGION=us to use https://us.api.openai.com/v1.
  • Set SB_OPENAI_API_BASE for an explicit endpoint override. Bare origins such as https://us.api.openai.com are normalized to the SDK base URL https://us.api.openai.com/v1.
  • OPENAI_BASE_URL is honored as a compatibility fallback when SB_OPENAI_API_BASE is not set.
  • Set OPENAI_ORG_ID or OPENAI_PROJECT_ID when a key can access multiple OpenAI organizations or projects.
  • Set SB_OPENAI_MAX_RETRIES to override the OpenAI SDK retry count. It defaults to 2.
  • If OpenAI grants access to a gated model that is not returned by the models API, set SB_OPENAI_MODEL to that exact model ID. sb models --provider openai includes the configured model alongside API-discovered models.

Provider-specific exceptions:

  • Bedrock uses standard AWS credentials and region selection instead of an API key.
  • Replicate uses REPLICATE_API_TOKEN rather than <PROVIDER>_API_KEY.
  • elevenlabs remains part of the voice runtime, not the chat-provider registry.
  • runway is not part of the chat-provider registry because it is a video-generation surface.

Storage Guidance

  • Do not commit secrets to .env, docs, or tracked config files.
  • Prefer the local helper tooling over ad hoc shell-history commands.
  • Only export secrets into the active shell when needed.

Troubleshooting

  • sb doctor is the first readiness check.
  • sb providers health is the first runtime check.
  • sb chat --provider <name> is the fastest functional smoke test.