Bring Your Own AI

Use your own OpenAI, Anthropic, Google Gemini, or xAI API keys with Ragnerock.

Ragnerock’s Bring Your Own AI (BYOAI) feature lets you configure your own AI provider for all agent-powered features: the Research Agent, annotation operators, and workflow processing. This enables you to leverage existing AI provider contracts, comply with data residency requirements, or use specialized models. All of these work while keeping Ragnerock’s data processing and search infrastructure intact.

Supported Providers

ProviderDefault ModelStatus
OpenAIgpt-5.4-miniSupported
Anthropicclaude-sonnet-4-6Supported
Google Geminigemini-3-flash-previewSupported
xAIGrok modelsSupported

Gemini is Ragnerock’s default provider, used when no custom configuration is set. You can use any model from these providers, as long as it meets the requirements below.

Model Requirements

Any model you configure must support:

  • Structured output: JSON mode for producing structured annotation results
  • Streaming responses: Token-by-token output for real-time agent interactions
  • Tool/function calling: Required for the Research Agent’s tool use

These capabilities are validated automatically when you create or update a configuration.

Creating a Configuration

Navigate to Settings (click your user icon in the sidebar) and select the AI Providers section.

  1. Click Add Provider
  2. Select the provider type (OpenAI, Anthropic, Google Gemini, or xAI)
  3. Enter your API key and the endpoint URL (pre-filled with defaults for each provider)
  4. Optionally set a config name, model name, timeout, and fallback to Ragnerock toggle
  5. Click Save. Ragnerock runs validation tests automatically before saving.
  6. Toggle the configuration to Active to start using it

The Add Provider form showing fields for provider type, API key, endpoint URL, and model name

Provider Setup

OpenAI

Select OpenAI as the provider type. Enter your API key (starts with sk-). The default model is gpt-5.4-mini. Any OpenAI model that supports structured outputs, streaming, and function calling is compatible. This includes GPT-5.4-mini and newer models.

Anthropic

Select Anthropic as the provider type. Enter your API key (starts with sk-ant-). The default model is claude-sonnet-4-6. Anthropic models support tool use and streaming natively.

Google Gemini

Select Gemini as the provider type. Enter your Gemini API key. The default model is gemini-3-flash-preview. Gemini is also Ragnerock’s default provider. Configuring your own Gemini key lets you use your own API quotas. Gemini’s large context window is particularly useful for processing long documents.

xAI

Select xAI as the provider type. Enter your xAI API key. Grok models are supported for both agent and annotation operations.

Validation

When you create or update a configuration, Ragnerock automatically runs four capability tests against your provider:

  1. Annotation test: Structured data production using JSON mode
  2. Streaming test: Token-by-token response delivery
  3. Tool calling test: Mock tool invocation
  4. Large input test: Handling ~5-6K token contexts

All four tests must pass before the configuration is saved. You can also run validation manually from the configuration card without saving, to test credentials before committing.

Managing Configurations

Your account can store multiple configurations, but only one can be active at a time. The active configuration is used for all agent-powered features: annotations, the Research Agent, and workflow operators.

In the AI Providers settings page, you can see all your configurations in a list with their provider type, model name, and active/inactive status.

Activating a Configuration

Toggle a configuration to Active to start using it. This automatically deactivates any previously active configuration.

Deactivating

Toggle a configuration to Inactive to return your account to Ragnerock’s default provider (Gemini).

Updating a Configuration

Click on a configuration to edit its settings. You can change the model name, timeout, fallback toggle, or credentials. If you update the provider type, endpoint, API key, or model, validation tests are re-run automatically.

Deleting a Configuration

Click Delete on a configuration card to remove it. Deleted configurations are soft-deleted and can no longer be activated.

Fallback Behavior

When creating or editing a configuration, enable the Fallback to Ragnerock toggle. With fallback enabled, Ragnerock automatically retries with its default Gemini provider if your configured provider returns an error or times out.

This ensures your workflows remain uninterrupted even if your provider experiences downtime. Usage is tracked separately for your provider and Ragnerock’s default.

Embeddings

Embeddings always use Ragnerock’s managed embedding service, regardless of your BYOAI configuration. This prevents dimension mismatches between different embedding models and avoids the need to re-embed your existing data when switching providers. We are actively exploring ways to support BYOAI for embeddings in a future release.

Security

API keys are encrypted at rest using envelope encryption:

  • Each configuration gets a unique Data Encryption Key (DEK)
  • DEKs are encrypted with a master Key Encryption Key (KEK) stored in a hardware-backed key management service
  • API keys are never returned in API responses. Only a masked hint is shown (e.g., sk-your...ykey).

Access to AI configurations is controlled by IAM permissions. Only account owners can create, modify, or delete configurations.

Next Steps