Configuration

Configure once, use everywhere. API keys, defaults, timeouts, and multi-tenant contexts made simple.

Table of contents

  1. Quick Start
  2. API Keys
  3. Default Models
  4. Rails Integration
  5. Next Steps

After reading this guide, you will know:

  • How to configure API keys for the providers you use.
  • How to set default models for chat, embeddings, and images.
  • How to wire RubyLLM into a Rails initializer.
  • Where to find provider, connection, and reference details.

Quick Start

The simplest configuration just sets your API keys:

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
end

That’s it. RubyLLM uses sensible defaults for everything else.

API Keys

Configure API keys only for the providers you use. RubyLLM won’t complain about missing keys for providers you never touch.

RubyLLM.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
  config.gemini_api_key = ENV['GEMINI_API_KEY']
end

Each provider has its own key (and sometimes region or project settings). For the full list of providers, organization headers, Vertex AI authentication, and OpenAI-compatible custom endpoints, see Provider Setup and Custom Endpoints.

Attempting to use an unconfigured provider will raise RubyLLM::ConfigurationError. Only configure what you need.

Default Models

Set defaults for the convenience methods (RubyLLM.chat, RubyLLM.embed, RubyLLM.paint):

RubyLLM.configure do |config|
  config.default_model = 'claude-sonnet-4-6'           # For RubyLLM.chat
  config.default_embedding_model = 'text-embedding-3-large'  # For RubyLLM.embed
  config.default_image_model = 'dall-e-3'              # For RubyLLM.paint
  config.default_speech_model = 'gpt-4o-mini-tts'       # For RubyLLM.speak
end

Defaults if not configured:

  • Chat: gpt-5-nano
  • Embeddings: text-embedding-3-small
  • Images: gpt-image-1.5
  • Speech: gpt-4o-mini-tts

Rails Integration

For Rails applications, create an initializer:

# config/initializers/ruby_llm.rb
RubyLLM.configure do |config|
  config.openai_api_key = Rails.application.credentials.openai_api_key
  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
  config.anthropic_api_base = ENV['ANTHROPIC_API_BASE'] # Available in v1.13.0+ (optional custom Anthropic endpoint)
  config.ollama_api_key = ENV['OLLAMA_API_KEY'] # Available in v1.13.0+ (optional for remote/authenticated Ollama)

  config.logger = Rails.logger

  config.request_timeout = Rails.env.production? ? 120 : 30
  config.log_level = Rails.env.production? ? :info : :debug
end

Next Steps

Table of contents