Providers and models

19 providers ship in the box. Model metadata — context windows, pricing, capabilities — comes from the models.dev registry, pruned at build time to the providers earshot supports.

Run earshot models for the live list; the table below is the shape of it.

Built in#

Model counts come from the vendored catalog snapshot and shift as vendors publish. Ollama discovers models live from whatever you have pulled.

How credentials resolve#

First match wins:

1. CLI flag — --api-key
2. Environment variable — the ones in the table above
3. Auth file — ~/.config/earshot/auth.json, written atomically, mode 0600 on POSIX
4. Ambient credentials — the AWS credential chain for Bedrock, Google Application Default Credentials for Vertex

On Windows the config directory is %APPDATA%\earshot. Override it with EARSHOT_CONFIG_DIR.

If nothing resolves, earshot exits 3 and names the variable to set, rather than failing later at request time with a provider's own error.

Wire adapters#

Seven AI SDK-backed wire adapters ship, plus Ollama’s native adapter:

openai-completions is the workhorse: OpenRouter, Groq, DeepSeek, xAI, Mistral, Together, Fireworks, Cerebras, DeepInfra, Nebius, Llama, LM Studio, and any endpoint you hand a base URL. This is why adding a provider is usually a one-line change — see Adding a provider.

Custom and local endpoints#

Any OpenAI-compatible server works with no code change — vLLM, llama.cpp, a corporate gateway, or a model the catalog doesn't know yet:

customProvider({
  id: 'my-vllm',
  baseUrl: 'http://gpu-box:8000/v1',
  apiKeyEnv: 'MY_VLLM_KEY', // optional
  models: [{ id: 'qwen3-coder', context: 256_000 }],
});

Known provider quirks#

These are real constraints, encoded in the design rather than discovered at runtime. Architecture covers how each is handled.

Signing in#

Most providers take an API key, from --api-key, an environment variable, or earshot auth login <provider> --api-key <key>.

OpenRouter also publishes a PKCE flow for third-party applications, and earshot auth login openrouter uses it: earshot binds a loopback port, sends you to OpenRouter in a browser, and exchanges the returned code for a key of your own. The URL is printed as well as opened, because over SSH or in a container there is no browser to open. What comes back is an ordinary OpenRouter key stored in auth.json; revoke it from your OpenRouter dashboard.

earshot auth list shows where each provider's credentials are coming from, and earshot auth logout <provider> forgets the stored ones — it says so when an environment variable is still in play, since a user who thinks they logged out and did not is worse off than one who knows.

Deliberately not supported#

Not oversights — each is a decision:

• Claude Pro/Max subscriptions. Anthropic's terms prohibit subscription OAuth outside Claude.ai and Claude Code, and it is enforced at the infrastructure level. Use an API key, Bedrock, or Vertex. earshot will not ship a workaround, and PRs adding one will be declined.
• Gemini Code Assist OAuth. Banned, and the endpoint is deprecated.
• GitHub Copilot subscriptions. No official third-party inference path exists.
• ChatGPT sign-in for Codex models. Not built, and not currently planned. It is the same mechanism as the entries above — a consumer subscription's credentials used by a client they were not issued for — and the fact that it is unlitigated rather than explicitly forbidden is not a difference earshot wants to rest a feature on. Use an OpenAI API key.

Refreshing the catalog#

earshot models --refresh          # fetch live from models.dev
bun run scripts/fetch-catalog.ts  # regenerate the vendored snapshot

The snapshot is pruned from models.dev's 4.4 MB down to ~380 kB: only supported providers, only the fields the harness reads, and only text-output chat models. Image and audio models arrive with no context limits and would ship as broken entries, so they are dropped.