models/catalog, REST
GET /models/catalog, and MCP meerkat_models_catalog. Configured
self-hosted aliases appear beside built-in models.
Current Defaults
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 login route’s current default: the provider’s catalog default, except
google_oauth (the Google Code Assist route), which uses gemini-3.8-flash
because the catalog’s Gemini default is not verified on Code Assist. A new
rkat auth login google binding also starts on gemini-3.8-flash, as does
the copilot_gemini route binding that rkat auth login copilot creates. This
applies only to the following reserved global binding/backend/auth profile
IDs and frozen legacy values:
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. Userkat models for every supported ID and its current limits.
- Anthropic
- OpenAI
- Gemini
- Self-hosted
Meerkat sends the model id unchanged on every Anthropic backend and keeps
no list of the platforms that serve each model. Anthropic serves
claude-fable-5-2 on the Claude API, Claude Platform on AWS, Claude
Models on Google Cloud and Microsoft Foundry, and on Amazon Bedrock only
through inference profiles: the global profile
global.anthropic.claude-fable-5-2 or the US geographic profile
us.anthropic.claude-fable-5-2. Bedrock offers no in-region access to
it, so the bare anthropic.claude-fable-5-2 does not run. Claude Mythos
5.2 (claude-mythos-5-2) is a model the catalog does not list, as Claude
Mythos 5.1 is: Anthropic serves it only to organizations it has verified,
on the Claude API, Claude Models on Google Cloud and Microsoft Foundry, on
Amazon Bedrock only through the inference profiles
global.anthropic.claude-mythos-5-2 and us.anthropic.claude-mythos-5-2,
and not on Claude Platform on AWS. Bedrock ids are not in the catalog:
declared under [models."global.anthropic.claude-fable-5-2"] (quoted, as
the id contains dots), it runs as a model id with no catalog row, without
the claude-fable-5-2 row’s local refusals or defaults.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 arelow, 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, and are replayed only to
the service the running process received them from (see
Continuity material and the service that issued it).
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.
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:
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. [realm.<realm>.copilot] configures the account and
its three routes once, from one credential source; a model only the account
lists runs on the route of the protocol its listed endpoints name, never one
chosen by its vendor (see
GitHub Copilot configured once).
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_modelwins 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. The exception is a binding on a credential account that also has a route of the model’s provider (a GitHub Copilot account’s routes): a request that names such a binding and no provider moves to the account’s route of the model’s provider.
- An uncataloged model needs an explicit typed provider/binding owner; a name
that merely begins with
gpt-orclaude-is never guessed. - On a route of a GitHub Copilot account, a model the registry does not define is defined for that build by the account’s model list: its provider is the family of the protocol its listed endpoints name, and its limits are the account’s. A model the account does not offer is refused, typed.
- On a route of a GitHub Copilot account, two IDs that are equal once every
.is read as-name the same model: the account listsclaude-opus-5.5, the catalogclaude-opus-5-5. A session created or resumed under either spelling runs the registry model under the registry ID, and the request names the account’s ID. An ID the account lists exactly wins; an ID that matches two of its entries and none exactly is refused. A live model switch and a fallback target take the registry ID only. Other routes match IDs exactly.
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.
Reasoning Effort
reasoning_effort is one provider-neutral setting for how much reasoning a
model spends: none, minimal, low, medium, high, xhigh or max
(one spelling each; x_high is not accepted here). Meerkat checks the level
against the selected model on the route that serves the request, writes the
provider’s own field, and reports what it sent.
The setting lives in the session’s provider params, so
provider_params.reasoning_effort is the same setting wherever provider
params are accepted (--param reasoning_effort=high on the CLI), except in a
schedule’s create spec, which does not take it in 0.9.15. A request
that gives both must give the same level in both, or it is refused as invalid
params.
From 0.9.15, a level in a mob profile is a one-way step for a rollback. A
mob whose definition holds a level in any profile, even a profile no member
ever used, cannot be read by 0.9.14: after a rollback 0.9.14 quarantines the
whole mob (its content is kept, and the mob is whole again on 0.9.15).
On Meerkat Meta it reaches further: a Meta gateway on 0.9.14 does not start
on a state directory that holds such a mob, so nothing stored in that
directory can be used there. Removing the level from the definition
afterwards does not help; the only way back is to destroy the mob on 0.9.15
and create it anew, which loses its members, their conversations and its
history. Where a rollback
must stay possible, set the level
on a session or a turn and clear it before rolling back; see
Rolling back to 0.9.14.
On a session. The level is part of the session’s LLM identity: it is
stored with the session and survives recovery, a resumed build, a hot swap of
the model, and a model fallback switch. A create request sets it. A turn (or
a resume input) changes it with a tri-state of its own: a level sets it for
that turn and the turns after it, {"action": "clear"} removes it, and
leaving the field out keeps it. It is independent of the other provider
params: a turn that replaces or clears provider_params keeps the level
unless it also names reasoning_effort (or its new params name the nested
key). The level applies to the session’s own model requests; requests to a
bound controller do not carry it.
What Meerkat writes. The level is translated to the field of the route
that serves the request:
Where the supported levels come from. A route states its levels from
exactly one source:
- the model catalog, on routes that forward to the provider’s own API and validation (the OpenAI, Anthropic and Gemini APIs and the cloud routes that serve them); the levels a model’s catalog row lists;
- the account’s model list, on GitHub Copilot: the levels the account’s list states for the model. Meerkat reads the list it already fetched for the account and ships no table of its own, so the same model can accept different levels on different accounts, and the catalog row of a model is never used for a Copilot route;
- the operator’s configuration, for a self-hosted model: its
reasoning_effort_levels(see Self-hosting models).
INVALID_PARAMS and typed data:
route names the endpoint as backend (for example openai_api,
anthropic_api, bedrock, vertex, google_genai, copilot,
self_hosted) and api (responses, chat_completions, messages,
generate_content, realtime). route, supported and facts are always
present, never left out: route is null when the client that serves the
request reports no route, and supported and facts are null when no
source states the levels or the source cannot be read now. facts is the
source of supported: catalog,
account or operator. The reason vocabulary is closed. The route names and
facts may grow, so a client keeps a value it does not know. Read the fields,
never the message text.
The refusal has the same shape wherever it is raised: when the session is
created or resumed, on a turn that changes the level or the model, and before
a provider request inside a turn (a Copilot account’s list can change between
turns). One case is not recognisable by its data kind: a meerkat_resume of, or
a meerkat_comms_send to, the session of a mob member that is not live, whose
own build is refused for the level in its profile, is answered the generic agent
error (-32013) with a message and no reasoning_effort_refused data.
From 0.9.15, over JSON-RPC a turn that names a refused level is answered when it
is asked, also while another turn of the session runs and for a stored
session that is not loaded: it changes nothing, and the running turn and
what is queued behind it go on. A turn that would change the session’s
model settings beside a provider-neutral level is taken when the session has
no unfinished work: on a session that holds a level that is every turn that changes the
model, the provider, the provider params, the auth binding or the level
itself (setting, changing or clearing it; a level inside provider_params
counts even when it equals the held one), and on a session that holds none
a turn that sets one. While the session has unfinished work such a turn is
answered SESSION_BUSY (send it again when the session has no unfinished
work; data kind reasoning_effort_change_needs_idle_session, the same kind when the
request only changed the model) and changes nothing: wait for the running
turn’s answer, then send it again. If nothing is running, an event queued on the
session counts: send a plain turn first (an autonomous mob member apart: see
Model settings on a busy session).
That answer is not a level refusal.
Plain turns and turns that repeat the session’s level with
reasoning_effort queue, and a session that holds no provider-neutral
level queues its turns as before, a model change, a clear and a provider’s
own effort parameter (provider_tag) included (the JSON-RPC reference has
the list). REST answers such a message for a session it holds live with
session is busy. A run refused inside a turn fails with run_failed reason
reasoning_effort_refused. It is never retried and never triggers a model
fallback. A provider-specific parameter the caller writes itself
(provider_params.provider_tag) stays available on every route, including
routes whose levels no source states.
Reports. A request that carries the level is reported; requests without
it report nothing new.
run_startedandrun_resumedcarryreasoning_effort: the resolution against the session’s route at the start of the run.request_reasoning_effort_resolvedis emitted once per request handed to the provider client with the level (turn requests, structured-output extraction, compaction summaries, fallback attempts), after the call settled. A call that failed after the hand-over is counted even when nothing reached the provider.- The run result carries
reasoning_effort: the level requested and each distinct resolution of those requests (sent), in first-use order, with a request count.
reasoning_effort_unsupported in model_fallback_skipped.
Finding the levels beforehand. models/catalog lists
reasoning_effort_levels in a model’s profile: the levels of the model’s
direct provider route. Levels that depend on an account or an operator
setting (a GitHub Copilot account’s list, a self-hosted model) are not in the
catalog; a caller learns them from the refusal’s supported and facts, and
sees the level that was applied in the run-start, per-request and result
reports.
Mob profiles. A profile sets the level of its members in its provider
params:
provider_params is in the profile’s resume_overrides and the profile’s
params name a level, which is then seated with them. Add
"reasoning_effort" to the profile’s resume_overrides to make the profile
decide it on resume in every case: the level its provider_params name, or
none.
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
{"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. {"type": "disabled"} turns
thinking off on the models that accept it: Claude Opus 4.8, Opus 4.7,
Sonnet 5, Sonnet 4.6, Sonnet 4.5, Haiku 4.5 and Opus 4.5 at any effort,
and Claude Opus 5 and Haiku 5.5 at high effort or below; Claude
Fable 5.2, Fable 5.1, Fable 5, Opus 5.5 and Sonnet 5.5 refuse it. 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 or a capped disabled
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.effort sets the response effort: low, medium, high, xhigh or
max; each model’s params_schema lists the levels it accepts. Every
request surface also accepts x_high as a spelling of xhigh, and
Meerkat sends xhigh to Claude either way. Responses, events and stored
records can carry either spelling, so a client reading them accepts both.Claude Fable 5.2, Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 accept a
replayed thinking block only while the system prompt, the tools and the
earlier messages it was produced under are unchanged, and refuse a
request that replays one after a change: Claude Fable 5.2 on every
account, the others on accounts created on or after 2026-08-31.
Meerkat changes the tools mid-session as MCP servers connect, so it asks
Anthropic to drop such blocks instead
(thinking.block_binding.prefix_mismatch_behavior: "drop_block", with
the thinking-binding-controls-2026-08-01 beta): beside configured
adaptive thinking, and beside the model’s own default,
{"type": "adaptive"}, when thinking is omitted, since these models
think by default. A model id with no catalog row (a dated snapshot, a
proxy alias, a [models.<id>] entry) gets the control beside
configured adaptive or enabled thinking, on every request; with
thinking omitted it gets none, since no catalog row names its default.
The control is never sent beside between_tools or disabled, and only on the
Anthropic API, Vertex and Foundry: Amazon Bedrock and the Copilot route
do not send it. A request to one of these models, or to a model id with
no catalog row, that carries no control replays the thinking blocks of
the turn in progress only, never those of completed turns, which
Anthropic allows (a completed turn’s server compaction block stays).
When a change within the turn (a tool loaded or a server connected
while it runs) still gets such a request refused with a 400, Meerkat
sends it once more without any thinking block, and without manual
enabled thinking, which needs one, logs a warning with the number of
blocks it removed, and returns the first error if that request fails
too, or the resend’s own error when it is one Meerkat retries (a rate
limit, an overload, a server or network error). A request that forces
a tool call with thinking omitted is sent as before, without the
control: Meerkat refuses a forced tool call beside explicit thinking,
and a forced call skips thinking on the models that accept one. The
model answers that turn without the dropped reasoning and the prompt
cache restarts at the first dropped block; Meerkat logs a warning
naming each dropped block.A session that moves from Claude Fable 5.2 to any model other than
Claude Mythos 5.2 loses Fable 5.2’s thinking for the turns that run
there, because Anthropic drops those blocks for every other model; the
request still succeeds.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 = { 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.provider_tools.<provider> toggle in config
or use rkat run --no-web-search for one run.
What later steps see of a search
A provider-native search runs inside one model step. What the next steps of the same turn, and later turns, still see of it depends on the provider:- OpenAI (Responses, stateless with
store: false, the default): on the public OpenAI API, a request with the hosted search tool asks for the sources each search consulted (include: ["web_search_call.action.sources"]). Later steps replay the search call with its query and those sources, and the answer with itsurl_citationannotations, plus the encrypted reasoning when reasoning is on. The text of the pages never comes back: a later step can name and search the sources again, but cannot quote what it read. The ChatGPT backend, Azure OpenAI and GitHub Copilot Responses wires replay the search call without its sources and the answer without its citations. All of this holds for a search the running process received from the service it is calling; see Continuity material and the service that issued it for a search from an earlier process or another service, of which later steps see only the answer text. - Anthropic: later steps replay the search results themselves, with their encrypted content.
- Gemini: grounding metadata has no place in a request, so later steps see only the model’s text.
store: true in the OpenAI provider
params: OpenAI then keeps each response and the next step continues from it
(previous_response_id), which is a retention choice. The Meerkat
web_search fallback tool returns its results as an ordinary tool result,
which every later step sees.
Continuity material and the service that issued it
The public OpenAI API, the ChatGPT backend, Azure OpenAI, GitHub Copilot and self-hosted OpenAI-compatible servers all speak the Responses grammar. What a response carries beyond the conversation (encrypted reasoning, hosted-tool call items, item ids, the response id) means something only to the service that issued it: another service cannot read the ciphertext and refuses the request. Meerkat replays such material only to the service the running process received it from. A service is a kind of backend at an endpoint: the base URL requests go to, or the configured self-hosted server ([self_hosted.servers.<id>]). Two Azure OpenAI resources, two self-hosted
servers, and the public API behind another base URL are different services.
- A step (one provider response) the process received from the service it is about to call replays exactly as that service returned it.
- Any other step is sent as the conversation it was: the assistant text as a
plain message, each tool call and its output paired by
call_id, and no reasoning item, hosted-tool item, item id, phase orprevious_response_id. This is the form a history from another provider family already takes. A step is replayed whole or in this form, never in part.
Refusals and Content Filters
Since 0.9.4, when a provider refuses a response or its content filter blocks it, the response ends with a typed stop instead of answer text. Meerkat commits nothing of that turn and runs none of its tool calls, and the run fails with classcontent_filtered. The run_failed event’s
error_report.reason names the stop and carries the provider’s own account
when it sent one:
stop is refusal or content_filter. detail is tagged by provider and
omitted when the provider sent none:
Each text field is capped at 4 KiB. Evidence of an unexpected shape reads as
absent and never turns the stop into a stream error. Branch on
stop; use
detail for display and diagnostics.
- OpenAI: a Responses
refusaloutput part, streamed (response.refusal.delta/.done) or in the terminal response, and a Chat Completionsdelta.refusalend the response as a refusal. The refusal wins over text and tool calls in the same response, and its text travels only as the detail. A Responsesincomplete_details.reasonor a Chatfinish_reasonofcontent_filterends it as a content filter. OpenAI-compatible self-hosted servers are read the same way. - Anthropic: a
refusalstop carries itsstop_detailswherever the stream puts it (inside or beside themessage_deltadelta, or onmessage_stop); themessage_deltavalue wins. A refusal whose stream is cut after the stop still ends as a refusal. - Gemini: a prompt blocked before any candidate
(
promptFeedback.blockReason, every reason includingOTHER) fails the run after one provider call. It is not retried, because the same prompt is blocked again. A candidate that finishes withSAFETY,RECITATION,BLOCKLIST,PROHIBITED_CONTENT,SPII,IMAGE_SAFETY,IMAGE_PROHIBITED_CONTENT,IMAGE_RECITATIONorLANGUAGEis a content filter;OTHER,MALFORMED_FUNCTION_CALLand unknown reasons are retried as an incomplete response.
web_search fallback tool reads its native search call’s stop the same
way; see Built-in tools.
In 0.9.3 and earlier the reason was null, an OpenAI refusal could be
committed as the answer, and a Gemini prompt block was retried as an
incomplete response. A 0.9.3 binary cannot read a session event log that
holds a 0.9.4 content-filtered run_failed line.
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:Image Generation
Thegenerate_image builtin routes independently of the active chat model:
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
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.
