Providers and models
miao brings its own model layer but not its own model: you connect the providers you already use, switch models inside a session, and give different agents different models. It runs locally with no miao or OpenCode account — credentials go straight to the provider.
Connect a provider
Section titled “Connect a provider”miao auth login <integration> <key> # store an API keymiao auth login <integration> <key> --account workmiao auth login <integration> <token> --oauthmiao auth # list credentials (never secrets)miao auth logout <integration> [--account NAME]You can also type /accounts in the TUI and complete OAuth or an API-key login
there. Credentials are written to the shared credential store, which the
miao / miao-dev / miao-preview entry points share, so you log in once.
A provider that
has a key in the environment is also picked up without login.
List and select models
Section titled “List and select models”miao models # provider/model ids this configuration and its credentials can addressmiao providers # routes, plugin count and stored credentialsmiao debug routes # the resolved route manifest as JSONProviders without a credential are left out because the TUI and miao run
cannot use them; use miao debug routes when you need to see what resolved.
Inside the TUI, /model or ctrl+x m switches the model; the last model used
per agent is remembered. A session without a chosen model uses the model
setting, written as <provider>/<model>:
{ "$schema": "https://mtty.dev/miao/config.json", "model": "anthropic/claude-sonnet-4-5",}Specialist agents can carry their own model and permissions; see the guide.
Where the catalog comes from
Section titled “Where the catalog comes from”Model metadata (names, context limits, capabilities, pricing) comes from
miao’s own catalog served at mtty.dev: the public models.dev
catalog with the provider miao maintains that models.dev does not list —
currently Command Code — merged in when the site
deploys. miao reads only this source; there is no models.dev fallback at
runtime. A snapshot is bundled into the build, so startup works offline.
You can point this at a different source:
| Variable | What it does |
|---|---|
MIAO_MODELS_URL |
Fetch the catalog from another URL |
MIAO_MODELS_PATH |
Use an exact local catalog file |
Command Code is a subscription provider: connect it
with miao auth login commandcode (browser-assisted) or set CMD_API_KEY; its
models are discovered from your account when it connects. OpenCode Zen / Go
remain available as optional third-party providers.
The mtty gateway
Section titled “The mtty gateway”mtty is mtty.dev’s own OpenAI-compatible gateway (https://my.mtty.dev/v1),
also maintained by miao in the catalog because models.dev does not list it.
Connect it with:
miao auth login mttyor set MTTY_API_KEY. Credentials are gateway API keys (the sk- prefix,
created in the /console/ of my.mtty.dev), sent as Authorization: Bearer. The
catalog currently declares mtty/deepseek-v4-1-flash-261017; run
miao models mtty to see what the gateway serves.
Custom providers
Section titled “Custom providers”The providers record in miao.jsonc adds or overrides a provider: its
credentials, wire protocol (api), extra request headers or body, model list,
and native-currency cost.
{ "$schema": "https://mtty.dev/miao/config.json", "providers": { "my-gateway": { "name": "My gateway", "env": ["MY_GATEWAY_API_KEY"], "currency": "USD", "models": { "llama-3.3-70b": { "name": "Llama 3.3 70B", "capabilities": { "tools": true, "input": ["text"] }, "cost": { "input": 0.2, "output": 0.6 }, "limit": { "context": 131072 }, }, }, }, },}env names the environment variables the provider reads its key from;
disabled hides a provider and its models even when credentials exist. The
api field selects the wire protocol, and the whole file is validated against
$schema. After editing, run miao models to confirm what the provider now
reports.
capabilities declares what the model can do, and it gates what the engine
sends it. tools gates tool calling; input lists the modalities the model
accepts (text, image, pdf). A route that omits image makes the engine
replace attached images with an omission marker and instructs the model to
tell the operator — so a vision model behind a custom provider must declare
["text", "image"], for example:
"deepseek-v4-1-flash-261017": { "name": "DeepSeek V4.1 Flash", "capabilities": { "tools": true, "input": ["text", "image"] },},Native engine routes
Section titled “Native engine routes”Sessions placed on the native engine reach these same providers through a trusted host route manifest. The mapping from a catalog provider to a native transport, the manifest fields, credential references, and the providers that deliberately stay on TypeScript are documented in Native engine provider routes. You still configure and authenticate providers here; the manifest is generated, not edited.
Cost and currency
Section titled “Cost and currency”Each provider turn records usage, time to first token, cache-hit data and an estimated cost; session totals appear in the sidebar. Costs are estimates from the model’s declared rates — your provider’s invoice is authoritative.
Pricing may be declared in the provider’s own currency (for example DeepSeek in CNY). Amounts are recorded in that currency and never converted; the ledger keeps one bucket per currency so CNY and USD are never added together.
Provider policy (experimental)
Section titled “Provider policy (experimental)”The experimental.policies list can deny use of a provider even when it is
configured and authenticated. Rules are matched in order and the last match
wins. The supported action is provider.use; resource accepts wildcard patterns:
{ "experimental": { "policies": [ { "effect": "deny", "action": "provider.use", "resource": "company-*" }, { "effect": "allow", "action": "provider.use", "resource": "company-eu" }, ], },}Troubleshooting
Section titled “Troubleshooting”miao debug configshows resolved configuration;miao debug infoshows installation and plugin information.miao debuglists the available subcommands.- An authentication error names the fix, usually
miao auth login <integration> <key>; log in again if the stored token expired. - A provider that shows no models is usually missing credentials or disabled by
policy; use
miao debug routesandmiao debug configto inspect what resolved.
See the guide for configuration precedence and the agent workflow comparison for how the provider layer evolved.
Synced from mttydev/miao@2f6034b.