> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Providers

> Model catalog, provider resolution, capability gating, parameters, and fallback.

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:

```bash theme={null}
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` |

<Warning>
  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.
</Warning>

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.

<Tabs>
  <Tab title="Anthropic">
    ```bash theme={null}
    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-5-5` | 1M | 128K | Recommended Sonnet model; adaptive thinking, effort default `high`, no sampling parameters |
    | `claude-sonnet-5` | 1M | 128K | Legacy Sonnet generation (still available upstream; prefer `claude-sonnet-5-5`); accepts forced tool choice, no mid-conversation system messages |
    | `claude-sonnet-4-6` | 1M | 64K | Previous Sonnet generation |

    ```toml theme={null}
    [agent]
    model = "claude-opus-5-5"
    ```
  </Tab>

  <Tab title="OpenAI">
    ```bash theme={null}
    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.1-sol` | 1.05M | 128K | Near-Astra performance at lower cost; 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`.

    ```toml theme={null}
    [agent]
    model = "gpt-6-astra"
    ```
  </Tab>

  <Tab title="Gemini">
    ```bash theme={null}
    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 |

    ```toml theme={null}
    [agent]
    model = "gemini-3.8-flash"
    ```
  </Tab>

  <Tab title="Self-hosted">
    Register an alias for an OpenAI-compatible endpoint:

    ```toml theme={null}
    [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](/guides/self-hosting-models).
  </Tab>
</Tabs>

## 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](https://developers.openai.com/api/docs/models/gpt-6-astra),
[reasoning and phase guidance](https://developers.openai.com/api/docs/guides/reasoning),
and [misalignment monitoring](https://developers.openai.com/api/docs/guides/safety-checks/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](/guides/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:

<CodeGroup>
  ```toml Anthropic-only feature selection theme={null}
  meerkat = { version = "=0.8.52", default-features = false, features = ["anthropic", "jsonl-store"] }
  ```

  ```toml All providers theme={null}
  meerkat = { version = "=0.8.52", features = ["all-providers", "jsonl-store"] }
  ```
</CodeGroup>

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:

<Tabs>
  <Tab title="Anthropic">
    ```bash theme={null}
    rkat run --model claude-sonnet-4-6 --params-json \
      '{"provider_tag":{"provider":"anthropic","thinking_budget_tokens":10000,"cache_control":"disabled"}}' \
      "Solve this problem"
    ```

    Thinking is typed per model: `{"type": "adaptive"}`,
    `{"type": "enabled", "budget_tokens": N}`, or, on Claude Sonnet 5.5,
    `{"type": "between_tools"}`, which turns off up-front thinking and is
    accepted only at `high` effort or below. A thinking type or budget
    (`thinking_budget_tokens`) the model does not accept, `top_k` on a model
    without top-k support, and `between_tools` above `high` effort are refused
    when the agent is built and again before each request, never sent to
    Anthropic. A generic `temperature` is omitted for models that reject
    sampling parameters.

    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`:

    ```toml theme={null}
    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.

    Under `automatic` and `system_and_conversation`, Meerkat also keeps one
    explicit breakpoint at the end of the previous run's output on every
    request of a run. The run's first request writes that entry even on a
    cold cache and later requests refresh it, so a `fork_off` child, whose
    first request is the forker's transcript up to its previous turn end,
    reads the shared prefix from cache.
  </Tab>

  <Tab title="OpenAI">
    ```bash theme={null}
    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 and
    the GPT-6 family also support `prompt_cache_enabled`, `prompt_cache_key`,
    and `prompt_cache_options` (`implicit` or `explicit`, with optional
    `30m` TTL). On the OpenAI API Meerkat defaults GPT-5.6 to `explicit` and
    GPT-6 to `implicit`, both with the `30m` TTL. Use `max`, not `ultra`, as
    the public provider effort.

    Explicit mode marks every input item, so the last input before the
    previous run's output always carries a breakpoint. In `implicit` mode on
    those models Meerkat adds one explicit breakpoint there and lowers inputs
    as content parts, so a run that starts on a cold cache still writes an
    entry a `fork_off` child cut at the previous turn end can read.
    `prompt_cache_retention = "in_memory"` is refused for these models when
    the agent is built; set the lifetime with `prompt_cache_options.ttl`.

    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](/rust/advanced#provider-parameters).
  </Tab>

  <Tab title="Gemini">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

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:

```toml theme={null}
[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](/concepts/configuration#model-fallback-settings)
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](/guides/image-generation) for the request shape.

## Rust Provider Features

```toml theme={null}
# Exactly pin the pre-1.0 Meerkat crate family.
meerkat = { version = "=0.8.52", 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.

## See Also

* [Auth and bindings](/concepts/auth-and-bindings)
* [Auth guide](/guides/auth)
* [Self-hosting models](/guides/self-hosting-models)
* [Capability matrix](/reference/capability-matrix)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.