Provider quickstart

Revka talks to your model provider through a single unified interface, so picking a provider is mostly a matter of two settings — default_provider and an API key — plus the right model ID. This page gets you from zero to a working chat with the three providers most people start on: OpenRouter (the default), Anthropic, and OpenAI. It also covers exactly how Revka resolves your credentials and how to override the provider per-run with environment variables.

If you have not installed Revka yet, start with Installation and the Quickstart. For the full list of supported back-ends, see the Provider catalog.

How provider config works

Three top-level keys in ~/.revka/config.toml control which model you talk to:

Key	Type	Default	Meaning
default_provider	String	"openrouter"	Provider ID (alias model_provider). Env: REVKA_PROVIDER or PROVIDER (legacy).
default_model	String	"anthropic/claude-sonnet-4.6"	Model ID (alias model). Env: REVKA_MODEL.
api_key	String?	none	Provider API key. Env: REVKA_API_KEY or API_KEY.

The fastest way to set all three is revka onboard, which writes config.toml for you. You can run it interactively or pass everything as flags for a non-interactive setup:

revka onboard                                          # interactive wizard
revka onboard --api-key sk-or-... --provider openrouter  # non-interactive

You can also edit ~/.revka/config.toml directly, or supply credentials entirely through environment variables — see Credential resolution order below.

Tip

List every provider Revka knows, with IDs and aliases, using revka providers. The active provider is marked, and custom:<URL> / anthropic-custom:<URL> entries appear for custom endpoints.

Run your first chat

Once a provider and key are configured, send a one-shot message with revka agent:

revka agent -m "Say hello in one sentence."

Drop the -m flag to open an interactive session instead. Key flags for revka agent:

Flag	Meaning
-m, --message <TEXT>	Send a single message (no interactive loop).
-p, --provider <ID>	Override the configured default_provider for this run.
--model <MODEL_ID>	Override the configured default_model for this run.
-t, --temperature <0.0-2.0>	Override the configured temperature.

This lets you try a provider without editing config at all:

revka agent -p openrouter --model openai/gpt-4o -m "Hello"
revka agent -p anthropic --model claude-sonnet-4-5-20250929 -m "Hello"

Pick a provider

OpenRouter (default)

OpenRouter is Revka’s out-of-the-box default. One key gives you access to 200+ models across vendors, and model IDs use the provider/model-name format (for example anthropic/claude-sonnet-4-6).

1. Get an OpenRouter API key — it starts with sk-or-.

2. Configure it:

   ~/.revka/config.toml

   default_provider = "openrouter"
   default_model    = "anthropic/claude-sonnet-4-6"
   api_key          = "sk-or-..."

   Or set it through the environment:

   export OPENROUTER_API_KEY="sk-or-..."

3. Run a chat:

   revka agent -m "Hello from OpenRouter"

Caution

On some OpenRouter models the default output cap (65536) returns HTTP 402 errors. If you hit that, set provider_max_tokens in config to a lower value. You can also raise the request timeout with provider_timeout_secs (default 120).

Anthropic

The Anthropic provider talks directly to the Anthropic Messages API, with native tool calling, vision, prompt caching, and SSE streaming.

1. Get an Anthropic API key — it starts with sk-ant-.

2. Configure it:

   ~/.revka/config.toml

   default_provider = "anthropic"
   default_model    = "claude-sonnet-4-5-20250929"
   api_key          = "sk-ant-..."

   Or set it through the environment:

   export ANTHROPIC_API_KEY="sk-ant-..."

3. Run a chat:

   revka agent -p anthropic -m "Hello from Claude"

Auth env vars and precedence. The Anthropic provider reads two variables:

• ANTHROPIC_OAUTH_TOKEN — a setup/OAuth token, checked first. This is for the subscription auth-setup flow, not normal API usage.
• ANTHROPIC_API_KEY — the standard sk-ant-… API key, used by most operators.

The default max_tokens is 4096; override it with provider_max_tokens.

Caution

Models in the claude-opus-4-7 line have deprecated the temperature parameter — Revka omits it automatically (the prefix match also covers patch variants like claude-opus-4-7-*). If you force a temperature on those models through another path, Anthropic returns HTTP 400.

OpenAI

The OpenAI provider uses the Chat Completions API (/v1/chat/completions), with native tool calling and support for the reasoning-content fields used by o and o3 family models.

1. Get an OpenAI API key — it starts with sk-.

2. Configure it:

   ~/.revka/config.toml

   default_provider = "openai"
   default_model    = "gpt-4o"
   api_key          = "sk-..."

   Or set it through the environment:

   export OPENAI_API_KEY="sk-..."

3. Run a chat:

   revka agent -p openai -m "Hello from OpenAI"

To point at a compatible or proxied endpoint, override the base URL with the api_url config key:

default_provider = "openai"
default_model    = "gpt-4o"
api_url          = "https://api.openai.com/v1"   # custom base (include /v1)

Revka appends /chat/completions to this base URL verbatim and does not add a /v1 segment for you, so include it yourself (the built-in default is https://api.openai.com/v1).

Note

Want a local model, a self-hosted endpoint, or a subscription-based login (Codex, Gemini CLI, Claude Code)? See Custom providers & local LLMs, Local, self-hosted & custom endpoints, and OAuth & subscription providers.

Credential resolution order

When Revka builds a provider, it resolves the API key in a fixed three-step priority. The first non-empty value wins:

1. Explicit config value — the api_key key in config.toml.

2. Provider-specific environment variable — for example OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY.

3. Generic fallback — REVKA_API_KEY, then API_KEY.

So a provider-specific variable always overrides the generic REVKA_API_KEY/API_KEY fallback. Note that for the anthropic, openai, and groq providers, the provider-specific env var (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY) takes precedence over a config.toml api_key value — this supports multi-provider and custom-gateway setups where the env var should win. For all other providers, a key set in config.toml takes priority over environment variables.

Note

Revka does not auto-load a .env file from the current working directory. However, it does auto-load the workspace .env file (~/.revka/workspace/.env) at startup — keys placed there are picked up without exporting. For a CWD .env, export the variables in your shell, source the file yourself, or use a tool like direnv.

Provider-specific key variables

Each provider has its own optional key variable. The most common ones:

Provider	Key env var	Key prefix
openrouter	OPENROUTER_API_KEY	sk-or-
anthropic	ANTHROPIC_API_KEY (or ANTHROPIC_OAUTH_TOKEN)	sk-ant-
openai	OPENAI_API_KEY	sk-
groq	GROQ_API_KEY	gsk_
perplexity	PERPLEXITY_API_KEY	pplx-
xai	XAI_API_KEY	xai-

See the Provider catalog for the complete list of providers and their key variables.

API key mismatch detection

Before constructing a provider, Revka checks the resolved key’s prefix against the selected provider and raises a readable error if they clearly do not match — for example an sk-ant- key used with the openai provider. This is a debugging aid for the common copy-paste mistake of mixing keys. The check is skipped for custom: providers and any provider configured with a custom api_url.

Tip

If a key leaks into an upstream API error body, Revka scrubs token-like patterns (sk-, ghp_, and similar) and shows [REDACTED] instead. Provider errors are also truncated to 500 characters.

Override the provider with REVKA_PROVIDER

You can switch providers per-run without touching config.toml using environment variables. There are two, with different precedence:

Variable	Behavior
REVKA_PROVIDER	Always wins over config when non-empty.
PROVIDER	Legacy fallback — only applied when config default_provider is unset or still openrouter.

Use REVKA_PROVIDER to force a provider regardless of what is in config:

REVKA_PROVIDER=anthropic revka agent -m "Hello"
REVKA_PROVIDER=ollama revka agent --model llama3.2 -m "Hello"

Caution

This trips up container users migrating from env-only setups: setting PROVIDER=openrouter in a Docker environment does not override an explicit non-default provider in config.toml. If you need a hard override, use REVKA_PROVIDER.

Provider environment variable overrides

Beyond the provider itself, the core runtime settings can all be set through the environment. These override the matching config.toml keys at startup:

Variable	Maps to config key
REVKA_PROVIDER / PROVIDER (legacy)	default_provider
REVKA_MODEL	default_model
REVKA_API_KEY / API_KEY	api_key
REVKA_TEMPERATURE	default_temperature
REVKA_EXTRA_HEADERS	extra_headers (format Key:Value,Key2:Value2)
REVKA_REASONING_ENABLED / REASONING_ENABLED	extended thinking mode

A fully env-driven run looks like this:

export REVKA_PROVIDER="anthropic"
export REVKA_MODEL="claude-sonnet-4-5-20250929"
export ANTHROPIC_API_KEY="sk-ant-..."
revka agent -m "Configured entirely from the environment"

Verify your setup

Confirm the provider and key are working before you build on them:

revka doctor models                       # probe every configured provider
revka doctor models --provider anthropic  # probe a single provider
revka models list                         # list cached models for the current provider
revka models refresh                      # refresh the model catalog from the provider
revka models status                       # show the current provider and model

revka doctor models reports a connectivity matrix with ok / skipped / auth/access / error status per provider — the quickest way to catch a bad key or an unreachable endpoint. (skipped appears for providers like Copilot that don’t support live model discovery.) The broader revka doctor run also validates that your provider, model, and key are set. See Diagnostics for the full report.

Next steps

Provider catalog Every supported provider: IDs, aliases, base URLs, env vars, and capabilities.

Cloud API providers Gemini, AWS Bedrock, and Azure OpenAI setup.

Local & custom endpoints Ollama, llama.cpp, vLLM, and custom: / anthropic-custom: prefixes.

OAuth & subscription providers Codex, Gemini CLI, Claude Code, Copilot, and OAuth logins.

Routing, reliability & tuning Fallback chains, model routing hints, timeouts, and max-tokens.

Chat with your agent Run interactive sessions and one-shot queries from the CLI.