Models and effort

A session's model decides which provider serves its requests. Mercury computes a default model from the recorded sign-ins unless an explicit choice outranks it, and /effort tunes the session's effort.

Model controls

/model: Picks the session model, says which model is in use and why, and includes searchable run it → /llmhost actions (run it on this Mac → when a model fits a local Mac).
/llmhost: Opens on Which model? with Machines I'm paying for and Vendor keys above MODELS (opening the cursor on the cheapest in-stock model), searching the 78 shipped recipes across 32 models alongside any public Hugging Face text-generation model, validating custom recipe files through Private recipes, checking GGUF headers (including tensor dimensions and ggml tensor types) and safetensors quantisations against the engines before renting, opening Bank · your weights to store weights locally or mirror kept Runpod and Vast.ai volumes, choosing the Weights source (Hugging Face, Private repository, This computer's Bank or Kept volume) on rental and stock-watch confirmations, showing where each model can run right now (on a running machine, on your own computer with mercury host, or on a GPU rented from Runpod, Vast.ai, Lambda, Hugging Face, Hyperstack, Verda or DigitalOcean) along with its quantization variants, conversations × context split and default thinking level, switching the renting session to the model when ready without overwriting your saved default model (and restoring the session's previous model on Terminate), showing live elapsed time and spend on Machine controls and in /usage (with Logs holding its page with a frozen clock until Esc), and pausing rentals on setup or runtime faults instead of terminating them (terminating automatically only after 2 hours idle or in an unanswered pause); see Providers and sign-in.
/effort: Tunes the session's effort.
/defaultprovider: Makes a provider the most recent sign-in in the sign-in ledger, which changes the computed default.
MERCURY_MODEL: Pins a model ahead of the computed default.
Session override: An explicit session choice outranks the computed default.

Default selection

A fresh, unpinned session starts on the provider of the most recent sign-in, on the newest model that credential can use. The default skips a gated row, and a provider with no usable row falls through to the next most recent sign-in.

Refreshing a token does not count as a new sign-in. Credentials that predate the sign-in history, including keys set through environment variables, come after all recorded sign-ins, and among those the configuration's defaultProvider comes first. This keeps the existing provider until the next sign-in.

With no sign-in anywhere there is no default. The home screen and /model say so and point at /logins.

m on the home screen, or on the new-session line at the top of the Session Concourse, opens the model picker with its effort row, and the pick becomes the default for new sessions. The engine.sessionDefaults setting set to false switches the key off. The picker keeps a refused save and a command-line launch override visible. In settings, engine.model holds the id or family word /model saved and engine.effort the level /effort saved; engine.roster limits which models can be selected, engine.disabledProviders switches off listed provider families (removing their rows from /model and mercury://models and disabling their bare family words while leaving stored keys untouched), engine.backups lists ordered backup engines to hop to when the active engine's provider is overloaded past the retry ladder, unreachable, refusing its sign-in after refresh, or no longer serving the model (--backup-model heads the list), and engine.pins maps known Anthropic model ids to the ids your own endpoint serves.

In settings, models.<id> (keyed by the full model id, including its provider or endpoint prefix) and models._default.<family> state model facts (contextWindow, maxOutputTokens, prices.input, prices.output, prices.cacheRead, prices.cacheWrite, efforts, images, reasoning and thinkingBudget); a lower window or output value, an omitted effort rung or false never lowers a capability already recorded for a known model, while models._default.<family> fills unstated facts for unknown model ids in that family.

A saved choice whose provider cannot serve it, because that provider has no sign-in here or its catalogue refused the model, hands the chat to the computed default: the chat starts on it and its first row says so, naming the provider, the reason and the two ways out, /logins <provider> to connect it and /model to change the default. Opening /model or /llmhost on a read-only configuration directory ignores EACCES, EPERM and EROFS when creating the host state directory so the picker opens cleanly, and running /clear or resuming a session when the previous chat's model cannot be reached starts the fresh chat on the default model with a one-line notice naming the unreachable model and /model (and unavailable compat model refusals point to /llmhost and /model). Keyless named endpoints (compat/<name>/<model>, including compat/box-<name>/<model> and compat/pod-<id>/<model>) work as the default model for new and /clear sessions without a stored API key, and custom compat/ endpoints using the responses dialect send the session's prompt_cache_key in /v1/responses requests. The saved choice is kept, so the next chat returns to it the moment that provider signs in, and /model in that chat saves a new default. When a catalogue has not been fetched yet, the chat starts on the saved choice. For a family with no recorded frontier id in the live list (such as a Gemini API-key-only home), the computed default selects the newest listed generation by version number. On a headless mercury run, --model local|compat|huggingface (and both SDKs in sdk/ and sdk-py/) resolves those family names against your configured endpoints and retains a recorded compat/<endpoint>/<model> across cold and warm session resume, while an unusable --model id is refused at the start of the run before any session is created or saved, so a later --continue in that folder starts on the default model instead of inheriting the bad id.

Model identifiers

Every model picker shows the model's full identifier and saves that identifier as shown. A family word already saved still resolves to its current model. A persisted identifier stays provider-qualified, and the namespace is removed before the request goes out. Each provider declares its identifier space in one table: a reserved qualified namespace, bare prefixes and aliases, or both.

compat/<vendor-id> and compat/<name>/<vendor-id>: The default custom OpenAI-compatible endpoint, or a named custom endpoint under compatProvider.<name> (including compat/pod-<id>/<model> for rented GPU pods and compat/box-<name>/<model> for own-computer model servers managed with /llmhost and mercury host).
openrouter/<vendor-slug>: OpenRouter, whose own identifiers are vendor/model slugs.
orcarouter/<vendor>/<model> and orcarouter/<alias> (and orcarouter/orcarouter/<name> for named routers): OrcaRouter.
huggingface/<org>/<model>[:provider|:policy]: Hugging Face.
nous/<vendor>/<model>: Nous Portal.
zen/<model-id>: OpenCode Zen.
together/<org>/<model>: Together AI.
groq/<model-id>, cerebras/<model-id> and fireworks/<model-id>: Groq, Cerebras and Fireworks AI text models.
melious/<model-id>[:speed|:price|:eco|:batch]: Melious AI chat models.
local/<model>: A local server, with the model as that server lists it.
Bare identifiers: Recognized by the prefixes and aliases each provider declares (gpt-* for OpenAI; gemini-* for Google; kimi-*, moonshot-* for Moonshot; deepseek-* for DeepSeek; glm-* for Z.AI; grok-* for xAI; muse-* (muse-spark-*, muse-wonder-1.0) for Meta; mistral-*, ministral-*, codestral-*, zai-glm-* for Mistral; minimax-* for MiniMax; command-*, north-*, c4ai-aya-*, tiny-aya-* for Cohere; qwen-*, qwen3*, qwen2*, qwq-*, qvq-* for Qwen; and Anthropic's Claude prefixes).

The family words deepseek, kimi, glm, grok, mistral, nous, zen, minimax, together, cohere, groq, cerebras, fireworks and qwen select each family's default text model (kimi selects the newest row the Moonshot account's live list serves, and for Qwen, qwen runs Qwen3.8 Max wherever it is a row). xAI's grok-* identifiers route to xAI, while muse-spark-* and muse-wonder-1.0 (Muse Wonder 1.0, 1,048,576-token context, image and tool support, minimal through max effort, $4 input / $0.20 cached / $20 output per million tokens) route to Meta. The muse family word selects the newest served Standard Muse Spark row. Meta's Contributor rows are labelled training permitted and need an explicit choice; neither muse nor the computed default selects one.

Meta's selectable rows come from the account's live model list. An empty successful list stays empty. An identifier absent from a fetched list is refused before chat; when the list is unavailable, an explicitly named identifier can be sent with a notice. Mercury's Meta connection replays only the conversation and tool results between turns.

An identifier no provider declares is treated as unrecognized. /model, /health and dispatch name it, and it is refused before any request, credentialed or not, unless one of your own settings carries it: an ANTHROPIC_* model pin naming it, or ANTHROPIC_BASE_URL pointed at a gateway that owns its identifiers. A model a provider refuses says why on its picker row and in the health check. When a model name is on neither mercury://models (the live list for your signed-in providers) nor mercury://models/known, the model may search the provider's published model page and ask you with what it found; it never launches a model from a web page.

Claude Sonnet 5.5 is listed as claude-sonnet-5-5, with the sonnet55 alias and a 1M-context option. The family word sonnet, including a saved "model": "sonnet", selects Sonnet 5.5. Sonnet 5 and Sonnet 4.6 retain their own rows. The standard input and output prices for Sonnet 5 and Sonnet 5.5 are $2 and $10 per million tokens in the picker and spend views, with cache reads at $0.10 per million tokens on Sonnet 5.5. Dated price and window pins also cover OpenAI's gpt-6-astra, gpt-6.1-sol ($2 input, $0.10 cached, $2.50 cache write, $10 output per million tokens), gpt-6-sol ($2 / $0.20 / $2.50 / $10), gpt-6-luna ($0.10 / $0.01 / $0.125 / $0.50), gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.6-cyber, gpt-5.5 ($5 / $0.50 / $30), gpt-5.5-pro, gpt-5.5-cyber, gpt-5.4, gpt-5.4-pro, gpt-5.4-mini and gpt-5.4-nano (with the 272K long-context multiplier where documented), and Google's gemini-4-argon ($2 input, $0.10 cached, $10 output per million tokens, with its December tier at $4 / $0.20 / $20).

A new session can start on a Claude model the account can run before that model's catalogue row appears. This applies to the home screen, /clear, --model, saved settings and crew, workflow and advisor choices; the provider decides whether the account can use the requested model.

Moonshot alias rows name the model actually served. When a model identifier is refused because it is served through an alias, the refusal names that alias. On Moonshot, kimi-k3.1-pro, kimi-k3.1-pro-highspeed and kimi-k3 (and the Kimi Code plan's k3.1-pro, k3.1-pro-highspeed and k3 rows, plus k3-256k at 262,144 tokens) have a 1,048,576-token context window, an output ceiling raisable to 1,048,576 (131,072 by default), thinking always on, dynamic tool loading, and low, high and max reasoning effort (default max on the platform rows and high on the Kimi Code plan rows); discontinued kimi-k2.5 is retired from the pins. The picker identifies signed-in state and fits around queued input and narrow windows.

Gemini's agent-only products are not callable models for a Mercury session, so the model picker omits them.

Change the session model

To change the session model:

Enter /model.
Select the target model, or type its identifier.
Read the transition preview.
Confirm the switch.

Mercury switches the conversation to the target model, and later requests go to that model's provider.

In a session, the model picker floats in the same window as the files menu, inside the chat view. Long model names stay clipped within their cells and the filter shows the end of the typed text. It opens at once on the rows it has and refreshes every signed-in family's list in the background: the Anthropic list through each signed-in door, every other signed-in family's catalogue, and the local servers' discovery, so a new model shows up in the picker when it ships. The rows sit under one heading per provider, the signed-in account's own provider on top and the rest by most recent use: a heading opens and closes like the files menu and says how many models are live under it, the sign-in shows as a sub-heading only when two are signed in, every row is alias, raw id, state and context size, an id Mercury cannot name reads new · no alias, and / opens a filter. A changed list replaces its rows in place with a one-line notice naming the family, the highlighted row follows its model when rows move, and a family with no credential sends nothing. Moonshot's default and picker rows follow the account's live model list (newest first, so /model kimi selects the newest served row), and a model the list lacks is refused before the call with the catalogue's own words. DeepSeek, xAI and Z.AI refresh their model lists when a credential is present; recorded rows with their date stand in while a list is unavailable. On DeepSeek, deepseek-v4-pro (DeepSeek V4 Pro, text-only) and deepseek-flash (DeepSeek V4.1 Flash, which accepts images and appends deferred tool definitions at the end of messages so the prompt cache prefix holds) have a 1,048,576-token context window and 393,216-token output ceiling in the pins (merged with live /models context_window, max_output_tokens and input_modalities facts when reported), and DeepSeek requests replay assistant reasoning_content across tool calls while thinking is on and omit it when thinking is off. With a Z.AI key, the picker reads the account's model list from the base the key is valid on (a key stored through /logins zai carries its proven plan; a key in ZAI_API_KEY or from a key command uses ZAI_KEY_PLAN set to coding or general, or learns the plan once per process from the key's models list when unset) and lists the model ids it names, newest first, with each row's window, vision capability (glm-5.3-flash, glm-5.3-flashx, glm-4.6v, glm-4.6v-flashx, glm-4.6v-flash, glm-4.5v) and reasoning dial taken from Z.AI's documentation; an id the documentation does not name is listed under its raw name with no window and no dial, and a model the list no longer carries leaves the group. Qwen rows name the console the key belongs to (QwenCloud or Model Studio) from the bound endpoint that accepted it. Meta uses its account's live list as described above. When Google refuses a catalogue read, the picker's group heading names the credential it tried, the status it got and the remedy. Each Anthropic model is listed once: Ctrl+W on a row controls its context size, and a saved choice made with the wider context lands on its model's row. The Config panel's choice picker refreshes the same live lists.

The preview is a frozen plan of what switching this history to the target does, with a typed disposition per item: what replays, which thinking drops, and how images are handled. It also counts the conversation against the target's context window before the first request. The count is the larger of the last count the provider reported for the conversation and a character estimate. The window is the target's as Mercury resolves it: the live catalogue's figure for the account when it has been read, else the pinned figure. While a window comes from a dated pin and the live list has not answered yet, the rail's context figure carries the word pin after the size, and ~ marks the conservative default no source has stated.

When the conversation does not fit, the preview says so with both numbers and where the window figure came from. Confirming compacts the conversation before the first request on the new model, and the summary is written by the model the conversation was built on, whose window holds it. A conversation that fits switches without compaction. Cancelling at the preview keeps the session's model, and the receipt names that model. The notice a switch earns about preserved thinking is written and shown in the turn whose request it describes, once per real switch, and the /model rows reach the session at the switch.

A local model's window is read from the server before a request is judged against it: the number is the server's, and a request that does not fit is refused with the window, its source and how to raise it. Ctrl+W on a local model's picker row, or /config → Local model window, sets the window the model is served with: auto takes the biggest of 32k, 64k, 128k or 256k that fits the machine, the rail's ctx row says why, and a window that does not fit is still saved, with the figures and the largest fitting window named.

On machines under 16 GiB, a manually chosen window that fits but leaves less than a tenth of usable memory or less than 1 GiB gets a warning with a smaller-window suggestion. This leaves Auto's choice of the largest window that fits unchanged.

Adjust the session's effort

Enter /effort to open a popup window like /model and set the session's reasoning effort within the effort vocabulary and ceiling of the selected model's provider. The popup lists one row per effort tier the model serves (auto first, max last, omitting any tier the model cannot run), each with a one-line description and the running tier marked current; ↑, ↓, the mouse wheel, Home and End move between rows, Enter applies the pick, Esc or a click outside closes with nothing changed, and /effort <level> typed applies at once. On self-hosted and OpenAI-compatible servers, /effort lists and sends each model's supported reasoning levels (low, high, max on GLM-5.3, GLM-5.3-Flash, DeepSeek V4.1/V4 Pro and Kimi K3; low, medium, xhigh on Qwen3.8; named thinking values from /api/show on Ollama, with cold Ollama launches reading the model's capability catalogue before the first request so the first turn sends your chosen /effort), sending chat_template_kwargs.reasoning_effort on llama.cpp, chat_template_kwargs.thinking (true when session thinking is on, false when off) on SGLang, and top-level reasoning_effort on vLLM, SGLang, Ollama and Kimi K3. If a server rejects a reasoning parameter or value, Mercury keeps your selected /effort and thinking and reports the server remedy instead of retrying at default effort.

Effort vocabulary and ceiling come from one capability source that answers every question Mercury asks of a model: identity, context window and output ceilings, thinking support, sampling, tools, media support and beta-header emission. That source re-reads live state on every call, so each model is judged by the capability set it serves now.

When a turn spends its ceiling thinking, it continues at the same effort: the thinking is kept and the model goes on to answer. A turn that closes inside its thinking says so.

How long Mercury waits on a silent model is the patience setting: normal, patient, or a custom object. Normal waits six minutes on a stream whose keep-alives are visible, fifteen on a quiet stream and on the non-streamed fallback, and gives recovery twenty minutes; patient doubles each. A custom object sets patience.streamIdleSeconds, patience.quietStreamIdleSeconds, patience.fallbackCeilingSeconds and patience.recoveryBudgetMinutes and inherits the normal values for the fields it omits. On self-hosted llama.cpp, vLLM, SGLang, Ollama and LM Studio servers, llama.cpp sessions coordinate distinct id_slot assignments across Mercury processes sharing a config home (with cache_prompt: true, keeping their slot through compaction and crewmate turns), llama.cpp and SGLang /metrics prefill speeds extend the first-byte allowance, self-hosted servers poll liveness during long prompt prefills instead of timing out after 30 seconds, the turn spinner shows its verb, elapsed time, ↓ token count, ~<N> tok/s output rate and reconnect count, the context compaction row shows compacting context, ↓ ~<tokens>, the progress bar and elapsed time, and streaming tool-call arguments count as live crewmate activity.

/effort saves the pick as the default for later sessions, as /model does. --effort <level> on the command line sets it for one launch, and a resumed session keeps the effort it ran on unless the command line says otherwise. When MERCURY_EFFORT_LEVEL overrides the effort for the session, a default-effort save says so and names the override. Every request record carries the effort: what was asked, what the provider applied, and how it was sent.

/defaultprovider makes a provider the most recent sign-in by your word, an entry in the same sign-in ledger the saved-choice rule reads.

A provider whose credential does not resolve refuses with the route to sign in or store a key; in /model, keyless custom endpoints retry in place without opening an unrelated sign-in screen, unreachable custom endpoints show Retry this server → and Remove this endpoint →, terminating a pod removes its provider entry, and opening /llmhost cleans up endpoints whose pods have ended. A tool-bearing request on a model that cannot take tools is refused before the request with a typed reason. A failed request keeps the session on its own provider: no switch silently falls back to another one.

Providers and sign-in · Permission modes · Sessions · Web search