Skip to content

providers.md

Latest commit

 

History

History
231 lines (167 loc) · 12.5 KB

providers.md

File metadata and controls

231 lines (167 loc) · 12.5 KB
Raw

Providers

dreb supports subscription-based providers via OAuth and API key providers via environment variables or auth file. For each provider, dreb knows all available models. The list is updated with every dreb release.

Table of Contents

Node Version and Streaming

Use Node.js 22 LTS. dreb's providers rely on stable SSE streaming, and Node 22 LTS is the supported runtime. Node 24 and Node 26 are known to break streaming: Node 26 changed ReadableStream buffering to "read one buffer at a time instead of reading ahead", which breaks the SSE stream parsers in the Anthropic SDK (v0.73.0) and OpenAI SDK (v6.26.0) that dreb uses.

If every provider fails with "request ended without sending any chunks", check your Node version and switch to Node.js 22 LTS.

Subscriptions

Use /login in interactive mode, then select a provider:

  • ChatGPT Plus/Pro (Codex)
  • GitHub Copilot
  • Google Gemini CLI
  • Google Antigravity
  • Kimi For Coding (requires active Kimi For Coding subscription)

Use /logout to clear credentials. Tokens are stored in ~/.dreb/agent/auth.json and auto-refresh when expired.

GitHub Copilot

  • Press Enter for github.com, or enter your GitHub Enterprise Server domain
  • If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
  • GPT-6 models, including github-copilot/gpt-6-astra, use the Responses API. Astra supports xhigh and native max thinking; access depends on the subscription and enabled models.
  • For adaptive Claude models such as Opus 4.8, readable thinking requires thinkingDisplay: "summarized" in SDK calls; enabling thinking alone can return only opaque signatures. See thinking display.
  • A registry context window can be lower than the endpoint's hard limit. Accepting a larger request does not change dreb's configured window. Usage-based overflow detection includes uncached input, cache reads, and cache writes.

Google Providers

  • Gemini CLI: Standard Gemini models via Cloud Code Assist
  • Antigravity: Sandbox with Gemini 3, Claude, and GPT-OSS models
  • Both free with any Google account, subject to rate limits
  • For paid Cloud Code Assist: set GOOGLE_CLOUD_PROJECT env var

OpenAI Codex

  • Requires ChatGPT Plus or Pro subscription
  • Personal use only; for production, use the OpenAI Platform API
  • The Codex catalog is derived automatically from the OpenAI Platform catalog at build time: frontier GPT models (GPT-5.5 and newer, named variants such as Sol/Terra/Luna/Astra, and gpt-daybreak-* previews) are mirrored onto openai-codex, plus gpt-5.4-mini. -pro, -mini, -nano, -chat and -codex variants and dated snapshots are excluded. The build fails loudly if a known Codex model disappears from the OpenAI catalog or a derived model lacks the catalog limits Codex requires (logic in packages/ai/scripts/codex-models.ts). Default is gpt-5.6-luna. Every Codex model uses a 272k context window, matching Codex CLI's default: the models support ~1M, but prompts above 272k input are billed at 2x. To use a larger window, override contextWindow for the model via modelOverrides in models.json.
  • Which models actually work depends on your ChatGPT plan/workspace — enterprise workspaces often enable new models later. An unavailable model fails with "model is not supported when using Codex with a ChatGPT account".
  • Astra supports text/image input, a conservative 272K configured context window, and up to 128K output tokens. Codex minimal effort is clamped to low; xhigh and max are sent unchanged.

Kimi For Coding

  • /login uses the Kimi Code OAuth subscription endpoint at https://api.kimi.com/coding/v1.
  • KIMI_API_KEY uses Kimi For Coding's Anthropic-compatible API at https://api.kimi.com/coding.
  • Built-in OAuth models are kimi-for-coding (default, 262k context), k3 (1M context), and kimi-for-coding-highspeed (262k context). Model availability is plan-dependent: the k3 1M-context ID and the kimi-for-coding-highspeed ID are only exposed when the subscription includes them, and kimi-for-coding-highspeed runs at roughly 6× speed for 3× quota usage. On login/refresh, dreb asks the Kimi API which models the subscription is entitled to and updates context, reasoning, image, tool-use, protocol, and thinking-effort metadata. Compatible newly discovered IDs are templated conservatively; if discovery fails, the static list remains available.
  • The OAuth k3 model is context-tiered: the Kimi endpoint serves it as k3-256k (256k context, cheaper) and k3 (1M context, stated to consume 2× the quota), and upgrading does not invalidate the prompt cache. The cheaper variant is exclusive to the Kimi for Coding OAuth endpoint — the pay-per-token Moonshot AI Platform does not expose it. dreb starts every session on the k3-256k wire ID and automatically upgrades to k3 once the session context passes the 256k cutoff (256k minus the default compaction reserve) instead of compacting. A user-lowered compaction threshold compacts before the cutoff and thus effectively disables the upgrade. Customizing k3's context window via models.json disables automatic tiering entirely, and compacted or fresh sessions return to the cheaper tier.
  • OAuth requests use the current Kimi Code device identity contract and share its stable ~/.kimi-code/device_id. Extra low-precedence headers can be supplied with newline-separated KIMI_CODE_CUSTOM_HEADERS values.
  • The OAuth coding endpoint accepts OpenAI-style multimodal content arrays with base64 image_url data URLs. dreb keeps a conservative 32k output-token cap because the managed model catalog does not currently advertise a per-model output limit.
  • Moonshot Open Platform uses a different base URL (https://api.moonshot.ai/v1); don't assume both routes expose identical behavior.

API Keys

Environment Variables or Auth File

Set via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
dreb
Provider Environment Variable auth.json key
Anthropic ANTHROPIC_API_KEY anthropic
Azure OpenAI Responses AZURE_OPENAI_API_KEY azure-openai-responses
OpenAI OPENAI_API_KEY openai
Google Gemini GEMINI_API_KEY google
Mistral MISTRAL_API_KEY mistral
Groq GROQ_API_KEY groq
Cerebras CEREBRAS_API_KEY cerebras
xAI XAI_API_KEY xai
OpenRouter OPENROUTER_API_KEY openrouter
Vercel AI Gateway AI_GATEWAY_API_KEY vercel-ai-gateway
ZAI ZAI_API_KEY zai
OpenCode Zen OPENCODE_API_KEY opencode
OpenCode Go OPENCODE_API_KEY opencode-go
Hugging Face HF_TOKEN huggingface
Kimi For Coding KIMI_API_KEY kimi-coding
MiniMax MINIMAX_API_KEY minimax
MiniMax (China) MINIMAX_CN_API_KEY minimax-cn

Reference for environment variables and auth.json keys: const envMap in packages/ai/src/env-api-keys.ts.

Auth File

Store credentials in ~/.dreb/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." }
}

The file is created with 0600 permissions (user read/write only). Auth file credentials take priority over environment variables.

Key Resolution

The key field supports three formats:

  • Shell command: "!command" executes and uses stdout (cached for process lifetime) 
    { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
{ "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
  • Environment variable: Uses the value of the named variable 
    { "type": "api_key", "key": "MY_ANTHROPIC_KEY" }
  • Literal value: Used directly 
    { "type": "api_key", "key": "sk-ant-..." }

OAuth credentials are also stored here after /login and managed automatically.

Cloud Providers

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Amazon Bedrock

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

Also supports ECS task roles (AWS_CONTAINER_CREDENTIALS_*) and IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).

dreb --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set AWS_BEDROCK_FORCE_CACHE=1 to enable cache points:

export AWS_BEDROCK_FORCE_CACHE=1
dreb --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

If you are connecting to a Bedrock API proxy, the following environment variables can be used:

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

Google Vertex AI

Uses Application Default Credentials:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file.

Custom Providers

Via models.json: Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See models.md.

Via extensions: For providers that need custom API implementations or OAuth flows, create an extension. See custom-provider.md and examples/extensions/custom-provider-gitlab-duo.

Resolution Order

When resolving credentials for a provider:

  1. CLI --api-key flag
  2. auth.json entry (API key or OAuth token)
  3. Environment variable
  4. Custom provider keys from models.json

Model Selection and Removed Models

The Codex catalog no longer lists the probe-verified unsupported routes gpt-5.1, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.3-codex, gpt-5.4, and gpt-5.3-codex-spark. This does not remove similarly named models from other providers.

If a saved default no longer exists, startup warns and prefers that provider's known default when available. For example, a missing saved openai-codex/gpt-5.4 selects openai-codex/gpt-5.6-luna even when OpenAI API credentials are also present. If the saved provider's default is unavailable, dreb can select another available model, with the warning naming the replacement. Use /model to save a new default.

For explicit CLI selection (--model provider/id or --provider provider --model id), if an ID exists exactly on another provider but only fuzzy-matches a different ID on the requested provider, dreb warns and uses the requested ID as a custom model rather than silently substituting the fuzzy match. Thus --model openai-codex/gpt-5.4 does not select gpt-5.4-mini; the unsupported ID is sent to Codex and can fail at the server. This is not an automatic migration or a general ban on fuzzy model patterns. Choose a supported model explicitly, for example:

dreb --model openai-codex/gpt-6-astra --thinking xhigh