class RubyLLM::Configuration
A Configuration holds every RubyLLM setting: provider credentials, default models, timeouts, retries, logging, and the model registry. The global instance is yielded by RubyLLM.configure and available as RubyLLM.config.
RubyLLM.configure do |config| config.openai_api_key = ENV['OPENAI_API_KEY'] config.anthropic_api_key = ENV['ANTHROPIC_API_KEY'] end
RubyLLM.context yields an isolated copy for per-request or per-tenant overrides.
Provider credentials such as openai_api_key are declared by each provider. See rubyllm.com/next/configuration-providers/ for provider credentials and endpoint settings.
Assigning an empty or whitespace-only string to any option stores nil, so unset environment variables behave as if the option was never set.
Attributes
Whether oversized local attachments are uploaded to provider file storage automatically. Default: true.
Whether acts_as_message records broadcast a chat’s messages and streamed chunks with Turbo. Needs turbo-rails and Action Cable. An acts_as_message model’s broadcasts: option overrides it. The chat UI generator turns it on. Default: false.
The model id used by RubyLLM.embed when no model is given. Default: 'text-embedding-3-small'.
The model id used by RubyLLM.paint when no model is given. Default: 'gpt-image-2'.
The model id used by RubyLLM.judge and Judge when no model is given. Default: 'jev-latest'.
The model id used by RubyLLM.chat when no model is given. Default: 'gpt-6.1-sol'.
The model id used by RubyLLM.moderate when no model is given. Default: 'omni-moderation-latest'.
The model id used by RubyLLM.ocr when no model is given. Default: 'mistral-ocr-latest'.
The model id used by RubyLLM.speak when no model is given. Default: 'gpt-4o-mini-tts-2025-12-15'.
The model id used by RubyLLM.transcribe when no model is given. Default: 'gpt-transcribe'.
The model id used by RubyLLM.animate when no model is given. Default: 'grok-imagine-video-1.5'.
How deprecation warnings are handled: :warn, :silence, or :raise. Default: :warn.
Faraday adapter used for HTTP requests. Default: :net_http.
Converters that turn a chat’s files into text for the model, as a Hash of MIME types to converters, tried before the ones RubyLLM ships. A type may end in /*, like "image/*", and a converter is anything that answers call with an Attachment and returns its text, or nil to pass it on. See FileStore::Converters. Default: {}.
config.file_converters["image/*"] = RubyLLM.file_store.converter.ocr
Proxy URL for all requests, such as 'http://proxy.example.com:8080'. HTTP, authenticated, and SOCKS5 proxies are supported. Default: nil.
Object receiving instrumentation events. It must respond to instrument(name, payload) and accept an optional block, like ActiveSupport::Notifications, which Rails apps use automatically. Default: nil.
Destination for the built-in logger, a path or an IO. Defaults to the RUBYLLM_LOG_FILE environment variable when set, $stdout otherwise.
Severity of the built-in logger. Defaults to Logger::DEBUG when the RUBYLLM_DEBUG environment variable says yes (true, 1, yes, or on), Logger::INFO otherwise.
Timeout in seconds for the regular expressions that scrub logged payloads. Defaults to the global Regexp.timeout, or 1.0 when none is set.
Whether raw streaming chunks are logged. Defaults to true when the RUBYLLM_STREAM_DEBUG environment variable says yes, false otherwise.
Number of times to retry failed requests. Default: 3.
Seconds a persisted chat’s run, or a tool call it runs, may take before another process treats it as crashed and resumes it. A run renews its claim as it streams and between steps; a tool call keeps its claim for this long, or for its Tool.max_run_time. Default: 600.
The HTTPS URL of your OAuth client metadata document. Authorization servers that support client ID metadata documents use it instead of registering RubyLLM. Default: nil.
Store for the OAuth credentials of MCP servers. Rails apps keep them in the ruby_llm_mcp_credentials table automatically. A store responds to +read(key)+, +write(key, data, owner:)+, and +delete(key)+. A store that several processes share also responds to +synchronize(key)+, running the block while no other process holds key, so only one of them refreshes a token at a time. Default: nil (keep them in memory).
Path of the writable JSON cache holding the model registry. Defaults to the operating system’s user cache directory. The copy bundled with the gem is used until this file exists.
Store object the model registry reads from and persists to. Rails apps using the acts_as helpers set this to the database store automatically. A store must respond to read, returning an array of Model entries, and may respond to +write(registry)+ to let Models#refresh persist. Default: nil (use model_registry_file).
Directory holding the gems and Python packages declared with Chat#with_code_execution, installed once and reused by every run. Defaults to a packages directory in the operating system’s user cache directory.
Whether Error#message leaves out what the provider wrote. When true, a provider’s error reads as its HTTP status, provider, and error code only, such as openai returned HTTP 400 (invalid_request_error), because providers often quote the request back. The text stays on Error#provider_message and the raw body on Error#response_body. Default: false.
Seconds to wait for a response before timing out. Default: 300.
Multiplier applied to the retry delay after each attempt. Default: 2.
Initial delay in seconds before the first retry. Default: 0.1.
Random jitter factor applied to retry delays. Default: 0.5.
Longest delay in seconds to wait between retries, including delays requested by the provider through rate-limit headers. When a provider asks for a longer wait, the request fails immediately instead of sleeping. Default: 30.
Where code from a model runs by default, such as the code Chat#with_code_execution executes: an MXC::Sandbox class from the mxc gem, its name as a String, or any sandbox Sandbox describes. Default: nil (nothing runs locally).
What isolates an MXC::Sandbox on Linux: :bubblewrap, which gives each run its own namespaces, or :landlock, which only restricts the files it can open and runs without network access. Other platforms ignore it, and so does a sandbox class that names its own backend. Default: :bubblewrap.
How chats run multiple tool calls from one response: false for sequential execution, true or :threads for threads, :fibers for fibers via the async gem. Default: false.
Seconds between status polls while RubyLLM.animate waits for a video job. Default: 5.
Seconds RubyLLM.animate waits for a video job to finish before raising an error. Default: 600.
Public Class Methods
Source
# File lib/ruby_llm/configuration.rb, line 49 def options option_keys.dup end
Returns the names of all declared options as an array of symbols, including options registered by providers.