Providers

Meerkat keeps one session and runtime model across Anthropic, OpenAI, Gemini, and configured self-hosted servers. Provider independence does not erase model differences: the selected catalog profile controls context limits, output limits, multimodal input, reasoning options, realtime support, provider-native tools, and the effective tool surface. Query the effective catalog instead of inferring capabilities from a model name:

rkat models

The same catalog is available through JSON-RPC models/catalog, REST GET /models/catalog, and MCP meerkat_models_catalog. Configured self-hosted aliases appear beside built-in models.

Current Defaults

Provider	Catalog default
Anthropic	`claude-opus-5-5`
OpenAI	`gpt-6-astra`
Gemini	`gemini-3.8-flash`
Global catalog default	`gpt-6-astra`

A catalog entry describes Meerkat’s supported capability contract, not the entitlement of a particular API organization, ChatGPT workspace, cloud deployment, or OAuth account. If gpt-6-astra is unavailable to the active OpenAI account, explicitly select gpt-5.5 or set a compatible binding default_model. Catalog-default changes alone do not migrate arbitrary configured models or binding defaults. The CLI has a separate, narrow built-in OAuth repair.

During interactive login, or read preparation when a matching stored token exists, the CLI can replace a built-in OAuth binding’s default_model with the provider’s current catalog default. This applies only to the following reserved global binding/backend/auth profile IDs and frozen legacy values:

Binding	Backend profile	Auth profile	Legacy `default_model` values repaired
`anthropic_oauth`	`anthropic_api`	`anthropic_oauth`	`claude-opus-4-6`, `claude-opus-4-7`, `claude-sonnet-4-6`
`openai_oauth`	`openai_chatgpt`	`openai_oauth`	`gpt-5.4`
`google_oauth`	`google_code_assist`	`google_oauth`	`gemini-3.1-flash-lite`

This is not a generic catalog migration: other binding IDs and other pins, including gpt-5.5, are not rewritten by this repair. A matching legacy value has no provenance marker distinguishing an old CLI sample from an operator pin. The replacement still requires account entitlement.

Provider Setup

The tables below are selected recommendations, not the exhaustive catalog. Use rkat models for every supported ID and its current limits.

Anthropic
OpenAI
Gemini
Self-hosted

export RKAT_ANTHROPIC_API_KEY="sk-ant-..."

Selected model	Context	Max output	Positioning
`claude-opus-5-5`	1M	128K	Default Anthropic model; thinking always on, effort default `medium`
`claude-opus-5`	1M	128K	Previous Opus generation
`claude-fable-5-1`	1M	128K	Recommended Fable model
`claude-fable-5`	1M	128K	Recommended previous Fable generation
`claude-opus-4-8`	1M	128K	Recommended previous Opus generation
`claude-sonnet-4-6`	1M	64K	Recommended Sonnet model

[agent]
model = "claude-opus-5-5"

export RKAT_OPENAI_API_KEY="sk-..."

Selected model	Context	Max output	Positioning
`gpt-6-astra`	1.05M	128K	Default OpenAI/global model; separate 922K input ceiling
`gpt-6-sol`	1.05M	128K	GPT-6 coding and agentic tier; separate 922K input ceiling
`gpt-6-luna`	1.05M	128K	GPT-6 efficient high-volume tier; separate 922K input ceiling
`gpt-5.6-sol`	1.05M	128K	GPT-5.6 catalog variant
`gpt-5.6-terra`	1.05M	128K	GPT-5.6 catalog variant
`gpt-5.6-luna`	1.05M	128K	GPT-5.6 catalog variant
`gpt-5.5`	1.05M	128K	Recommended fallback
`gpt-5.3-codex`	400K	128K	Supported Codex model
`gpt-realtime-2`	128K	32K	Realtime audio/text and still-image input

gpt-5.6 is a catalog alias for gpt-5.6-sol.

[agent]
model = "gpt-6-astra"

export RKAT_GEMINI_API_KEY="AIza..."

Model	Context	Max output	Positioning
`gemini-3.8-flash`	1M	64K	Default and recommended Gemini model
`gemini-3.7-flash`	1M	64K	Supported previous Flash generation
`gemini-3.5-flash`	1M	64K	Supported previous Flash generation
`gemini-3.1-pro-preview`	1M	64K	Advanced preview reasoning
`gemini-3.1-flash-lite-preview`	1M	64K	Lightweight preview model

[agent]
model = "gemini-3.8-flash"

[self_hosted.servers.ollama]
transport = "openai_compatible"
base_url = "http://127.0.0.1:11434"
api_style = "chat_completions"

[self_hosted.models.gemma-4-31b]
server = "ollama"
remote_model = "gemma4:31b"
display_name = "Gemma 4 31B"
family = "gemma-4"
tier = "supported"
context_window = 256000
max_output_tokens = 8192
vision = true
image_tool_results = false
inline_video = false
supports_temperature = true
supports_thinking = true
supports_reasoning = true
supports_web_search = false
call_timeout_secs = 600

Server entries contain connection facts only. Credentials belong to a realm binding for provider = "self_hosted", with an auth method of none, api_key, or static_bearer. Legacy credential fields on self_hosted.servers are rejected as unknown config.See Self-hosting models.

GPT-6 Astra: Initial Responses Support

Meerkat supports ordinary Astra Responses requests: text/image input, text output, application function calls, and the existing provider-native web-search path. Its 1,050,000-token context has a distinct 922,000-token input ceiling and a 128,000-token output ceiling (including reasoning). Context-budget projections apply the input ceiling in addition to the output reserve; estimated context pressure is not exact provider token accounting. Supported reasoning efforts are low, medium, high, xhigh, and max. none, temperature, top_p, and log-probability controls are unsupported. Astra does not support the Realtime endpoint; it cannot back live/*. For compatibility, existing OpenAI temperature and generic top_p settings remain omitted from provider requests rather than gaining a new rejection policy. Unsupported reasoning efforts and log-probability fields fail the existing typed validation. store: false remains the default. Assistant-item commentary and final_answer phases, supported output order, and terminal encrypted reasoning associated with assistant output survive transcript persistence and input replay. The existing orphan-only compatibility rule remains: replay strips reasoning from an assistant message with no replayable text, assistant item, or tool output, even if that reasoning is encrypted. An empty identified assistant item still counts as output. Provider response and item IDs are continuity metadata, never Meerkat session identity. misalignment_policy_violation is a typed terminal policy stop, not an authentication error: Meerkat does not refresh credentials, retry, switch providers, or reset the conversation to evade it. This integration does not enable async/pending provider tools, early tool dispatch, Responses WebSocket steering, configuration_update, tool search, programmatic calling, new hosted tools/MCP/connectors, provider multi-agent orchestration, provider compaction/conversations, or background responses. Unsupported output execution semantics fail explicitly; additive inert metadata does not disable established behavior. Direct OpenAI support does not establish Astra availability on Azure, Copilot, ChatGPT OAuth, or a custom endpoint. See OpenAI’s model contract, reasoning and phase guidance, and misalignment monitoring.

Environment Credential Precedence

RKAT_* variables let Meerkat use dedicated credentials without taking over keys used by other tools.

Provider	Resolution order
Anthropic	`RKAT_ANTHROPIC_API_KEY`, `ANTHROPIC_API_KEY`
Public OpenAI	`RKAT_OPENAI_API_KEY`, `OPENAI_API_KEY`
Gemini	`RKAT_GEMINI_API_KEY`, `GEMINI_API_KEY`, `RKAT_GOOGLE_API_KEY`, `GOOGLE_API_KEY`
Azure OpenAI	`RKAT_AZURE_OPENAI_API_KEY` plus `RKAT_AZURE_OPENAI_ENDPOINT`, then unprefixed equivalents

If public OpenAI and only unprefixed Azure variables are both present, public OpenAI wins. Setting either prefixed Azure selector makes a complete Azure key/endpoint pair the OpenAI environment default. Environment credentials are synthesized as a typed ephemeral binding and go through the same provider runtime resolver as configured bindings.

Public OpenAI API Versus ChatGPT OAuth

OpenAI has separate backend/auth pairs:

Backend	Auth	Account surface
`openai_api`	`api_key`, `static_bearer`, or host authorizer	Public OpenAI API organization/project
`chatgpt_backend`	`managed_chatgpt_oauth` or host-supplied ChatGPT tokens	ChatGPT/Codex subscription and workspace
`azure_openai`	`azure_api_key`	Azure deployment
`copilot`	`github_copilot_oauth`	GitHub Copilot account

These are not interchangeable credential paths. A model ID available to an API organization may be unavailable to a ChatGPT workspace, and vice versa. rkat models reports the Meerkat catalog, not account entitlement. Keep a binding’s backend, auth method, and default model aligned. Copilot is also available beneath the Anthropic and Gemini provider families. Those routes share one account-scoped credential while preserving the model’s provider identity and selecting the account-advertised wire dialect. Model entitlement is therefore an account observation, never a fixed property of the Meerkat model registry. See Auth for the full backend/auth compatibility matrix.

Model And Provider Resolution

The effective model registry is the built-in catalog plus configured custom and self-hosted entries. Provider resolution uses exact registry ownership, not name prefixes.

An explicit model wins.
An explicit provider constrains every omitted-model choice.
An explicit binding infers and validates its provider; its default_model wins when the model is omitted.
Otherwise Meerkat checks compatible configured defaults and then the provider/global catalog default.
A known provider/model mismatch fails before agent construction.
An uncataloged model needs an explicit typed provider/binding owner; a name that merely begins with gpt- or claude- is never guessed.

All public session-creation surfaces use the same resolver. Inherited bindings retain the realm that owns their config. Rust applications can select only the provider adapters they use:

meerkat = { version = "=0.8.42", default-features = false, features = ["anthropic", "jsonl-store"] }

meerkat = { version = "=0.8.42", features = ["all-providers", "jsonl-store"] }

Cargo features are additive across the dependency graph; another dependency can still enable additional provider features.

Capability-Gated Projection

The durable session transcript remains provider-neutral and ordered. Each adapter projects that transcript and the effective tool surface to its wire format:

unsupported multimodal blocks or tools are rejected or hidden according to the model profile;
system instructions remain ordered, and a limited provider projection fails when it cannot represent their positions without changing meaning;
a model switch or fallback recomputes context/output limits and tool visibility from the newly selected catalog profile.

The transcript itself is not rewritten merely because a different provider wire has stricter placement rules.

Provider Parameters

Use --param for common top-level parameters such as temperature. Use the typed provider_params.provider_tag envelope for provider-specific fields:

Anthropic
OpenAI
Gemini

rkat run --model claude-sonnet-4-6 --params-json \
  '{"provider_tag":{"provider":"anthropic","thinking_budget_tokens":10000,"cache_control":"disabled"}}' \
  "Solve this problem"

Anthropic also supports top_k and the prompt-cache policies automatic (the default on the Anthropic API, Vertex, and Foundry), system_prefix, system_and_conversation, and disabled, plus cache_ttl (5m, the default, or 1h). Bedrock and Copilot do not accept automatic caching: they default to disabled and reject an explicit automatic locally. In a mob profile or AgentBuildConfig the same knobs nest under provider_tag:

provider_params = { provider_tag = { provider = "anthropic", cache_control = "disabled" } }

A flat provider_params = { cache_control = "disabled" } fails the whole definition parse: ProviderParamsOverride and AnthropicProviderTag are both deny_unknown_fields, so the misplaced key is rejected before the agent boots.

rkat run --model gpt-5.6-terra --params-json \
  '{"provider_tag":{"provider":"open_ai","reasoning_effort":"max","reasoning_mode":"pro","reasoning_context":"all_turns","text_verbosity":"high"}}' \
  "Prove this theorem"

The catalog validates each model’s reasoning-effort subset. GPT-5.6 also supports prompt_cache_enabled, prompt_cache_key, and prompt_cache_options (implicit or explicit, with optional 30m TTL). Use max, not ultra, as the public provider effort.Meerkat’s default prompt_cache_key is one key per model (meerkat:profile:openai:<model>), shared across sessions so identical system and tool prefixes can reuse OpenAI’s prefix cache. The key only routes requests; it never proves a cache hit, and OpenAI still needs a byte-identical prefix. A caller-supplied key wins. Sharing maximises cross-session reuse of the static prefix, while very high aggregate request rates on one model can overflow OpenAI’s routing for a single key; see Rust SDK advanced.

rkat run --model gemini-3.8-flash --params-json \
  '{"provider_tag":{"provider":"gemini","thinking_level":"medium"}}' \
  "Analyze this data"

Consult rkat models for the selected model’s effective parameter schema.

Provider-native web search is enabled by default for catalog models that support it. Disable the relevant provider_tools.<provider> toggle in config or use rkat run --no-web-search for one run.

Model Fallback

Runtime model fallback is disabled by default. Operators must explicitly enable it and provide a non-empty ordered chain; catalog defaults are never a chain:

[model_fallback]
enabled = true

[model_fallback.policy]
cross_provider = true

[[model_fallback.chain]]
model = "claude-opus-4-8"
provider = "anthropic"

[[model_fallback.chain]]
model = "gpt-5.5"
provider = "openai"
auth_binding = { realm = "global", binding = "openai_oauth" }

Fallback activates only when generated recovery authority classifies the failure as recoverable and the core loop determines that switching is pre-stream safe. The default triggers are capacity and provider unavailability, after three failed attempts. Transport and empty output do not migrate by default, and a switch is suppressed after visible text or reasoning. An accepted switch is sticky for later turns and recovery. Meerkat re-resolves credentials, output limits, context limits, provider parameters, and tool visibility for the target. Actual materialized context, output reserve, tool/modality/structured-output parity, and credential authority must pass both selection and precommit admission. Cross-provider targets without opt-in and targets with unavailable credentials are typed skips, not fatal configuration errors; malformed configuration and credential-store faults still surface. New fallback-origin unsafe resumes require explicit reconfiguration. Older sticky routes have no proven fallback provenance and are not automatically healed. See fallback configuration for precedence and deferred migration boundaries. Ordinary same-model retry is separate. Genuinely unknown provider failures now consume the existing bounded retry budget, while explicit terminal classes remain non-retryable.

Image Generation

The generate_image builtin routes independently of the active chat model:

Provider	Default image target
OpenAI	`gpt-image-2`
Gemini	`gemini-3.1-flash-image-preview`

Generated bytes are stored as realm blobs and can be fetched through CLI, RPC, MCP, or SDK blob methods. REST responses carry blob references but the current REST router does not expose a blob-byte fetch route. See Image generation for the request shape.

Rust Provider Features

# Exactly pin the pre-1.0 Meerkat crate family.
meerkat = { version = "=0.8.42", features = ["sqlite-store", "session-store"] }

The meerkat facade enables anthropic, openai, and gemini by default. Use all-providers as a convenience alias or disable default features and select only the provider/storage capabilities your embedded build needs. Shipped CLI/RPC/REST/MCP binaries use product feature sets rather than the minimal library profile.

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

Current Defaults

Provider Setup

GPT-6 Astra: Initial Responses Support

Environment Credential Precedence

Public OpenAI API Versus ChatGPT OAuth

Model And Provider Resolution

Capability-Gated Projection

Provider Parameters

Model Fallback

Image Generation

Rust Provider Features

See Also

​Current Defaults

​Provider Setup

​GPT-6 Astra: Initial Responses Support

​Environment Credential Precedence

​Public OpenAI API Versus ChatGPT OAuth

​Model And Provider Resolution

​Capability-Gated Projection

​Provider Parameters

​Model Fallback

​Image Generation

​Rust Provider Features

​See Also

Current Defaults

Provider Setup

GPT-6 Astra: Initial Responses Support

Environment Credential Precedence

Public OpenAI API Versus ChatGPT OAuth

Model And Provider Resolution

Capability-Gated Projection

Provider Parameters

Model Fallback

Image Generation

Rust Provider Features

See Also