Skip to content

providers.md

Latest commit

 

History

History
241 lines (176 loc) · 11.1 KB

providers.md

File metadata and controls

241 lines (176 loc) · 11.1 KB
Raw

Providers

Choose a supported provider, authenticate, then select a model. Base Context does not choose a provider or model automatically. Accounts, usage limits, and billing belong to the provider you select.

First-time setup

  1. Start base-context.
  2. Open /login and select a provider. For a supported subscription, follow its browser authorization link. For API-key authentication, enter that provider's key. Bearer and cloud credentials use the provider-specific setup below.
  3. Open /model and choose a supported model. The selected provider/model is saved for later sessions.

For command-line selection, list the supported models and name both parts:

base-context model list
base-context --provider openai --model gpt-5.4
# Equivalent:
base-context --model openai/gpt-5.4

An API key alone does not select a model. A missing or unavailable saved model is not silently replaced with another provider. For models outside the built-in list, register the provider/model in models.json first.

Authentication availability

Use /login for supported subscription OAuth or API-key authentication. The built-in subscription routes are OpenAI Codex (ChatGPT), Anthropic (Claude Pro/Max), and GitHub Copilot. Open the provider's browser link and complete its authorization steps. Access and usage limits depend on your provider account.

Credentials are stored in ~/.base-context/auth.json (BASE_CONTEXT_HOME can select another state root). Normal OAuth storage persists credentials and refreshes them when needed. Provider-specific bearer and cloud credentials are described below. Prime integrations are disabled; this does not disable other registered OAuth providers.

ChatGPT / Codex subscription

  1. Open /login and choose OpenAI Codex.
  2. Open the displayed browser link and sign in with the ChatGPT account that has Codex access. Complete the callback or paste the requested authorization response when prompted.
  3. Open /model and explicitly choose an openai-codex model available to your account.

An OpenAI API key belongs to the separate openai provider; it is not required for the Codex subscription route. Anthropic API-key authentication is likewise separate from Claude subscription login. Logging in does not automatically select or replace a model.

The SDK also offers an optional, explicitly injected read-only Codex backend for existing credentials. Only that mode disables login, refresh, credential writes, and API-key fallback. It does not restrict normal interactive subscription login. See SDK authentication.

API Keys

Environment Variables or Auth File

Use /login in interactive mode and select a provider to store an API key in auth.json, or set credentials via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
base-context
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
DeepSeek DEEPSEEK_API_KEY deepseek
Google Gemini GEMINI_API_KEY google
Mistral MISTRAL_API_KEY mistral
Groq GROQ_API_KEY groq
Cerebras CEREBRAS_API_KEY cerebras
Cloudflare AI Gateway CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID) cloudflare-ai-gateway
Cloudflare Workers AI CLOUDFLARE_API_KEY (+ CLOUDFLARE_ACCOUNT_ID) cloudflare-workers-ai
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
Fireworks FIREWORKS_API_KEY fireworks
Kimi For Coding KIMI_API_KEY kimi-coding
MiniMax MINIMAX_API_KEY minimax
MiniMax (China) MINIMAX_CN_API_KEY minimax-cn
Xiaomi MiMo XIAOMI_API_KEY xiaomi
Xiaomi MiMo Token Plan (China) XIAOMI_TOKEN_PLAN_CN_API_KEY xiaomi-token-plan-cn
Xiaomi MiMo Token Plan (Amsterdam) XIAOMI_TOKEN_PLAN_AMS_API_KEY xiaomi-token-plan-ams
Xiaomi MiMo Token Plan (Singapore) XIAOMI_TOKEN_PLAN_SGP_API_KEY xiaomi-token-plan-sgp

Reference for environment variables and auth.json keys: env-api-keys.ts.

Auth File

Store credentials in the owned ~/.base-context/auth.json (BASE_CONTEXT_HOME selects another product root):

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "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-..." }

Writable OAuth storage is used only when the configured route permits it. The read-only existing-Codex subscription mode does not write this file or refresh credentials. Shell-backed API-key entries execute commands; use only trusted local configuration, never unreviewed imported instructions.

Cloud Providers

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# root endpoints are auto-normalized to /openai/v1
# 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).

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

Register custom application inference profile IDs in models.json before selecting them. 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
base-context --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

Cloudflare AI Gateway

CLOUDFLARE_API_KEY can be set via /login. The account ID and gateway slug must be set as environment variables.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
base-context --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

Routes to OpenAI and Anthropic through Cloudflare AI Gateway. OpenAI uses the OpenAI passthrough route (/openai) with native OpenAI model IDs such as gpt-5.1. Anthropic uses the Anthropic passthrough route (/anthropic) with native Anthropic model IDs such as claude-sonnet-4-5. Cloudflare-hosted @cf/... models are available through the separate cloudflare-workers-ai provider.

AI Gateway authentication uses CLOUDFLARE_API_KEY as cf-aig-authorization. Upstream authentication can be one of:

Mode Request auth Upstream auth
Workers AI Cloudflare token only Cloudflare-native
Unified billing Cloudflare token only Cloudflare handles upstream auth and deducts credits
Stored BYOK Cloudflare token only Cloudflare injects provider keys stored in the AI Gateway dashboard
Inline BYOK Cloudflare token plus upstream Authorization header The request supplies the upstream provider key

For normal Base Context usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream Authorization header for the Cloudflare AI Gateway provider, for example via a models.json provider/model override.

Cloudflare Workers AI

CLOUDFLARE_API_KEY can be set via /login. CLOUDFLARE_ACCOUNT_ID must be set as an environment variable.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
base-context --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Base Context automatically sets x-session-affinity for prefix caching discounts.

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