Skip to content

Users add any number of model providers and switch models inside a conversation with /model and /models. There is no automatic routing between models.

With no providers.json, Mob starts on the offline demo model, which echoes the prompt, until a provider is added. OpenRouter’s :free models are a way to start without paying. OpenCode Zen is offered with the user’s key for its paid models only: its free models are for OpenCode’s own clients (Zen docs), so Mob hides them. Conversations and saved facts are sent to the chosen model’s provider.

Terminal window
mob provider add deepseek --key-stdin # presets need only a key
mob provider add work --chat https://relay.example/v1 --key-stdin --models gpt-6,claude-sonnet-5
mob provider add ollama # local servers need no key
mob provider add magpie # the magpie gateway on this machine
mob provider ls # keys shown masked
mob provider rm work

Preset IDs: opencode, openai, anthropic, deepseek, google, openrouter, moonshot, zhipu, ollama, lmstudio, magpie. Any other OpenAI- or Anthropic-compatible endpoint is added with --chat or --anthropic.

In the web workspace, Add a model provider in the model picker, or Model providers in the runner menu, does the same for the common presets, Ollama and LM Studio, or a custom base URL. The dialog lists the connected providers first, with the default’s marked, then every provider as a tile with its logo; choosing one shows its sign-in or key field, with a link to where its keys are made, and the default model under Default model. Choosing a connected provider replaces its key. Connecting calls POST /api/providers with {preset, url?, protocol?, key, model?}, lists the provider’s models and saves it as the default model, replacing a provider with the same ID. Without a named model, OpenRouter starts on one of its free models that takes tools. The browser runner saves through its own plugin route instead, which only offers vendors a browser can call.

In any conversation, in every client and channel:

  • /models [FILTER] lists the models of every provider, with what each can do.
  • /model NAME switches this conversation. NAME may be provider/model, a model ID, or a unique fragment (/model sonnet); :low/:high… picks a reasoning level.
  • /model default NAME sets the default for conversations without their own.

In the Web UI, choosing the model name below the message input opens a searchable picker above the button, without a backdrop or blocking the conversation; on a phone it opens as a sheet from the bottom of the screen. The button shows the model’s name and, when one is chosen, its reasoning level.

  • Search and the Reasoning, Vision, Tools and Free chips narrow the list; with more than one provider, a provider menu narrows it to one.
  • Each row shows the model’s logo, name, what it can do and its context window, and marks the current model. Rows are grouped by provider, and a long provider list such as OpenRouter folds by vendor.
  • Follow the default (with the default model’s name) and Recent, the last few models chosen in this browser, come first when nothing is filtered. Recent choices are kept in this browser only.
  • On a wide window, a card beside the list tells about the model under the pointer or focus, or else the current one: its full ID, context, maximum output, reasoning levels, input kinds, tools and price.
  • When the current model takes reasoning levels, a Reasoning control under the list picks one (provider/model:level) or the model’s default.
  • The footer offers Make … the default (the same as /model default NAME) or names the default, and Add a model provider.

Arrow keys move between visible choices and Enter selects one; Enter in a nonempty search selects its first result in an expanded group, or does nothing if all result groups are collapsed. Clicking outside or pressing Escape closes it; choosing a model also closes it. Choosing a model saves the conversation’s model setting through POST /api/conversations/{id}/model ({model}, empty for the default), the same change /model makes; it sends no chat and keeps the message draft. If the choice is refused, the picker stays open and the error shows. The model can be changed while a reply is being written: that reply keeps its model and the choice applies from the next one. A provider whose model list fails stays visible with its error, including when search or a filter is active.

magpie serves every provider signed in to it from a gateway on this machine. mob provider add magpie reads the port from magpie’s settings.json (read only), checks that magpie answers there, and lists the models turned on in magpie. Calls carry the key magpie-mob, so magpie’s usage and routing rules see them as Mob’s.

Concept Answers Lives in
Catalog what a model can do: context, output limit, reasoning levels, tools, images, price packages/core/src/provider/catalog.ts, the models.dev catalog cached in XDG cache mob/models.json, refreshed daily
Provider how to reach a vendor: base URL per protocol, key, picked models, overrides packages/core/src/provider, providers.json beside config.yaml
Driver one wire protocol packages/core/src/llm/openai.ts (Chat Completions), anthropic.ts (Messages), demo.ts; or aisdk.ts, both protocols through the AI SDK’s provider packages
Model a callable provider/model[:effort] Model, from ProviderRegistry.resolve
  • It is the only source of providers and keys. Mode 0600, atomic writes, the replaced file kept as providers.json.bak. An unreadable file is an error, never an empty list. Keys are never read from environment variables.
  • The API and CLI show keys masked. The running service reloads the file when it changes; a rejected change leaves the providers in effect unchanged.
  • mob provider add|ls|rm edits it directly; the service and CLI lock the file while changing it. Pointing a provider at another URL requires its key again (--key-stdin) or --clear-key, and --clear-headers when it has saved headers, so credentials never follow a provider to a new host.
  • Presets are curated because models.dev has no key pages, regional or multi-protocol endpoints.
  • Mob never sniffs URLs to pick vendor behavior and does not present itself as another vendor’s client.
  • Model lists come from the vendor’s /models (or modelsURL), else the preset’s models.dev entry. Picks that held every listed model take in models listed since (pickedFrom). Unknown models are assumed to take tools.
  • Protocol per model: the user’s modelPrefs.api, else the only endpoint, else Anthropic Messages for Claude models, else Chat Completions.

Mob speaks to providers with its own protocol code unless driver: aisdk (MOB_DRIVER=aisdk) chooses the AI SDK’s provider packages (@ai-sdk/openai-compatible, @ai-sdk/anthropic) while they are tried. Either way the engine keeps its own loop: the AI SDK driver calls the model’s doStream directly, not streamText, so tool calls come back unexecuted and unvalidated. What stays Mob’s on both drivers:

  • requests go through send: a request whose response stops arriving fails as stalled, and one that failed before its response began is sent again, honouring Retry-After, never once text is streaming;
  • a refusal is worded by statusError, with every credential masked and a prompt too long for the window told apart, so Mob summarizes and retries;
  • model output is held to the same limits (response size, tool calls, their IDs, names and arguments), and a failure keeps what arrived before it;
  • Anthropic caching marks the tools, system prompt and latest message, and thinking shares the requested tokens, leaving at least half for the answer.

packages/core/test/drivers.test.ts runs one set of recorded streams against both drivers.

  • conversations.model holds the /model choice; empty follows providers.json’s default. Each assistant message records its model and usage, priced from the catalog.
  • Choosing a model is a setting of the conversation, not part of its transcript: /model, /models and the web picker add no messages, and the next reply records the model it ran on. /model and /models are answered by the service for every client and channel through the command registry, and their answers are shown once, not stored. (Conversations from before this change may still hold /model commands recorded as kind='command'; they are shown as they were and never sent to a model.) POST /api/conversations/{id}/model saves the choice for the local UI, starting a conversation not started yet, which stays unlisted until something is said in it. Only the owner may switch: the local UI, the Telegram bot’s user, the first allowed WeChat user and email’s owner address.
  • History is replayed as real tool calls and results, so one model can continue another’s work. Reasoning from earlier turns is not replayed; it belongs to its model. How history is fitted to the model is in Turns and context.

Several keys per provider, fallback chains, routing groups, quotas and subscription sign-ins. Without a cached catalog (first run offline), models lack metadata until the catalog arrives, and history falls back to the last 40 messages.