Skip to content
stepper

Providers & keys

Configure API keys for five AI providers with environment variables, OS keyring, or explicit config.

stepper supports five AI providers. Configure your API keys via explicit config, environment variables, or OS keyring — precedence matters, and each provider has different auth requirements.

Supported providers

  • ollama-cloud — Ollama cloud models
  • oMLX — local Apple-Silicon MLX on localhost:8000/v1; auth is optional
  • OpenAI — OpenAI API
  • Anthropic — Anthropic Claude models
  • Codex — ChatGPT via OAuth

Key precedence

stepper looks for API keys in this order: explicit apiKey in config → environment variable → OS keyring. The first match wins.

Set keys via environment variables

Use the STEPPER_<PROVIDER>_API_KEY convention, where the provider name is uppercased and hyphens are replaced with underscores.

sh
# Env var: STEPPER_<PROVIDER>_API_KEY  (provider uppercased, '-' → '_')
export STEPPER_ANTHROPIC_API_KEY=sk-ant-...
export STEPPER_OLLAMA_CLOUD_API_KEY=...

Store keys in OS keyring

Use the keyring commands to securely store and manage keys. The keyring stores keys in your system's credential manager (Keychain on macOS, secret-service on Linux, Credential Manager on Windows).

sh
# Store a key (prompts for the key on stdin):
stepper auth set-key <provider>

# Remove a key:
stepper auth delete-key <provider>

Codex (ChatGPT) OAuth

To use the Codex provider (ChatGPT), authenticate with OAuth. This opens a browser and stores credentials locally.

sh
# Codex (ChatGPT) OAuth — opens a browser, stores ~/.stepper/codex-auth.json (0600):
stepper auth login --codex

oMLX local setup

oMLX on localhost usually needs no API key, making it ideal for local development without external dependencies.

Key precedence is explicit config apiKey > env var > OS keyring. Always set keys before running stepper, or it will fail at runtime when a layer requires a model from an unconfigured provider.