Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Reorder providers in README and other places
Alishahryar126c5b3569803
diff --git a/.env.example b/.env.exampleindex 4358bc5e..8f830f1f 100644--- a/.env.example+++ b/.env.example@@ -64,7 +64,7 @@ OLLAMA_BASE_URL="http://localhost:11434"# All Claude model requests are mapped to these models, plain model is fallback# Format: provider_type/model/name-# Valid providers: "nvidia_nim" | "open_router" | "mistral" | "mistral_codestral" | "deepseek" | "kimi" | "wafer" | "lmstudio" | "llamacpp" | "ollama" | "opencode" | "opencode_go" | "zai" | "fireworks" | "gemini" | "groq" | "cerebras"+# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "wafer" | "kimi" | "cerebras" | "groq" | "fireworks" | "zai" | "lmstudio" | "llamacpp" | "ollama"MODEL_OPUS=MODEL_SONNET=MODEL_HAIKU=diff --git a/README.md b/README.mdindex f1aac8c2..3e67a871 100644--- a/README.md+++ b/README.md@@ -37,7 +37,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code to any p## What You Get- Drop-in proxy for Claude Code's Anthropic API calls.-- Seventeen provider backends: NVIDIA NIM, OpenRouter, Mistral La Plateforme, Mistral Codestral, DeepSeek, Kimi, Wafer, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, Z.ai, Fireworks AI, Google AI Studio (Gemini), Groq, and Cerebras Inference.+- Seventeen provider backends: NVIDIA NIM, OpenRouter, Google AI Studio (Gemini), DeepSeek, Mistral La Plateforme, Mistral Codestral, OpenCode Zen, OpenCode Go, Wafer, Kimi, Cerebras Inference, Groq, Fireworks AI, Z.ai, LM Studio, llama.cpp, and Ollama.- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers.- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (Claude Code must opt in to Gateway model discovery; see [Model Picker](#model-picker)).- Streaming, tool use, reasoning/thinking block handling, and local request optimizations.@@ -183,34 +183,7 @@ Popular examples:This provider uses Wafer's Anthropic-compatible endpoint at `https://pass.wafer.ai/v1/messages`.-### 8. [LM Studio](https://lmstudio.ai/)--Start LM Studio's local server and load a model. In the Admin UI, keep or update `LM_STUDIO_BASE_URL`, then set `MODEL` to the model identifier shown by LM Studio, prefixed with `lmstudio/`.--Prefer models with tool-use support for Claude Code workflows.--### 9. [llama.cpp](https://github.com/ggml-org/llama.cpp)--Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests.--In the Admin UI, keep or update `LLAMACPP_BASE_URL`, then set `MODEL` to the local model slug, prefixed with `llamacpp/`.--For local coding models, context size matters. If llama.cpp returns HTTP 400 for normal Claude Code requests, increase `--ctx-size` and verify the model/server build supports the requested features.--### 10. [Ollama](https://ollama.com/)--Run Ollama and pull a model:--```bash-ollama pull llama3.1-ollama serve-```--In the Admin UI, keep or update `OLLAMA_BASE_URL`, then set `MODEL` to the same tag shown by `ollama list`, prefixed with `ollama/`.--`OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. Example model slugs include `ollama/llama3.1` and `ollama/llama3.1:8b`.--### 11. [OpenCode Zen](https://opencode.ai/)+### 8. [OpenCode Zen](https://opencode.ai/)Get an API key at [opencode.ai/auth](https://opencode.ai/auth).@@ -229,7 +202,7 @@ Popular examples:Browse available models at [opencode.ai](https://opencode.ai).-### 12. [OpenCode Go](https://opencode.ai/)+### 9. [OpenCode Go](https://opencode.ai/)Get an API key at [opencode.ai/auth](https://opencode.ai/auth) (same as OpenCode Zen).@@ -243,7 +216,7 @@ Popular examples:Browse available models at [opencode.ai](https://opencode.ai).-### 13. [Z.ai](https://z.ai/)+### 10. [Z.ai](https://z.ai/)Get an API key at [Z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).@@ -258,7 +231,7 @@ Popular examples:Browse models at [Z.ai](https://z.ai).-### 14. [Fireworks AI](https://fireworks.ai/)+### 11. [Fireworks AI](https://fireworks.ai/)Get an API key at [fireworks.ai/account/api-keys](https://fireworks.ai/account/api-keys).@@ -268,7 +241,7 @@ Fireworks exposes an **Anthropic-compatible** Messages API at `https://api.firewBrowse models at [fireworks.ai/models](https://fireworks.ai/models).-### 15. [Google AI Studio (Gemini)](https://aistudio.google.com/)+### 12. [Google AI Studio (Gemini)](https://aistudio.google.com/)Get a Gemini API key at [Google AI Studio](https://aistudio.google.com/apikey) (see Google's [Gemini OpenAI compatibility](https://ai.google.dev/gemini-api/docs/openai) docs).@@ -281,7 +254,7 @@ Popular examples:- `gemini/gemini-2.5-flash`- `gemini/gemini-3.1-flash-lite`-### 16. [Groq](https://console.groq.com/)+### 13. [Groq](https://console.groq.com/)Get an API key at [console.groq.com/keys](https://console.groq.com/keys).@@ -293,7 +266,7 @@ Reasoning-heavy models expose extra knobs documented under [Groq reasoning](httpBrowse models at [console.groq.com/docs/models](https://console.groq.com/docs/models).-### 17. [Cerebras Inference](https://inference-docs.cerebras.ai/quickstart)+### 14. [Cerebras Inference](https://inference-docs.cerebras.ai/quickstart)Sign up and create an API key in the [Cerebras Cloud Console](https://cloud.cerebras.ai) (see [Quickstart](https://inference-docs.cerebras.ai/quickstart)).@@ -301,6 +274,33 @@ In the Admin UI, set `CEREBRAS_API_KEY`, then route with `MODEL` such as `cerebrCerebras exposes an OpenAI-compatible API at `https://api.cerebras.ai/v1` ([OpenAI compatibility](https://inference-docs.cerebras.ai/resources/openai)). Non-standard request fields should go in `extra_body` when using the OpenAI client; see the same page. For reasoning models and parameters, see [Reasoning](https://inference-docs.cerebras.ai/capabilities/reasoning). This proxy follows other OpenAI-compat adapters for thinking via `reasoning_content` when Claude-style thinking is enabled.+### 15. [LM Studio](https://lmstudio.ai/)++Start LM Studio's local server and load a model. In the Admin UI, keep or update `LM_STUDIO_BASE_URL`, then set `MODEL` to the model identifier shown by LM Studio, prefixed with `lmstudio/`.++Prefer models with tool-use support for Claude Code workflows.++### 16. [llama.cpp](https://github.com/ggml-org/llama.cpp)++Start `llama-server` with an Anthropic-compatible `/v1/messages` endpoint and enough context for Claude Code requests.++In the Admin UI, keep or update `LLAMACPP_BASE_URL`, then set `MODEL` to the local model slug, prefixed with `llamacpp/`.++For local coding models, context size matters. If llama.cpp returns HTTP 400 for normal Claude Code requests, increase `--ctx-size` and verify the model/server build supports the requested features.++### 17. [Ollama](https://ollama.com/)++Run Ollama and pull a model:++```bash+ollama pull llama3.1+ollama serve+```++In the Admin UI, keep or update `OLLAMA_BASE_URL`, then set `MODEL` to the same tag shown by `ollama list`, prefixed with `ollama/`.++`OLLAMA_BASE_URL` is the Ollama server root; do not append `/v1`. Example model slugs include `ollama/llama3.1` and `ollama/llama3.1:8b`.+### 18. Mix Providers By Model TierEach model tier can use a different provider by setting `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` in the Admin UI. Leave a tier blank to inherit `MODEL`.diff --git a/config/provider_catalog.py b/config/provider_catalog.pyindex a1180bb1..e6b587f1 100644--- a/config/provider_catalog.py+++ b/config/provider_catalog.py@@ -75,6 +75,25 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {proxy_attr="open_router_proxy",capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),),+ "gemini": ProviderDescriptor(+ provider_id="gemini",+ transport_type="openai_chat",+ credential_env="GEMINI_API_KEY",+ credential_url="https://aistudio.google.com/apikey",+ credential_attr="gemini_api_key",+ default_base_url=GEMINI_DEFAULT_BASE,+ proxy_attr="gemini_proxy",+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),+ ),+ "deepseek": ProviderDescriptor(+ provider_id="deepseek",+ transport_type="anthropic_messages",+ credential_env="DEEPSEEK_API_KEY",+ credential_url="https://platform.deepseek.com/api_keys",+ credential_attr="deepseek_api_key",+ default_base_url=DEEPSEEK_ANTHROPIC_DEFAULT_BASE,+ capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),+ ),"mistral": ProviderDescriptor(provider_id="mistral",transport_type="openai_chat",@@ -95,13 +114,34 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {proxy_attr="codestral_proxy",capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),),- "deepseek": ProviderDescriptor(- provider_id="deepseek",+ "opencode": ProviderDescriptor(+ provider_id="opencode",+ transport_type="openai_chat",+ credential_env="OPENCODE_API_KEY",+ credential_url="https://opencode.ai/auth",+ credential_attr="opencode_api_key",+ default_base_url=OPENCODE_DEFAULT_BASE,+ proxy_attr="opencode_proxy",+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),+ ),+ "opencode_go": ProviderDescriptor(+ provider_id="opencode_go",+ transport_type="openai_chat",+ credential_env="OPENCODE_API_KEY",+ credential_url="https://opencode.ai/auth",+ credential_attr="opencode_api_key",+ default_base_url=OPENCODE_GO_DEFAULT_BASE,+ proxy_attr="opencode_go_proxy",+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),+ ),+ "wafer": ProviderDescriptor(+ provider_id="wafer",transport_type="anthropic_messages",- credential_env="DEEPSEEK_API_KEY",- credential_url="https://platform.deepseek.com/api_keys",- credential_attr="deepseek_api_key",- default_base_url=DEEPSEEK_ANTHROPIC_DEFAULT_BASE,+ credential_env="WAFER_API_KEY",+ credential_url="https://www.wafer.ai/pass",+ credential_attr="wafer_api_key",+ default_base_url=WAFER_DEFAULT_BASE,+ proxy_attr="wafer_proxy",capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),),"kimi": ProviderDescriptor(@@ -120,69 +160,43 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {"native_anthropic",),),- "wafer": ProviderDescriptor(- provider_id="wafer",- transport_type="anthropic_messages",- credential_env="WAFER_API_KEY",- credential_url="https://www.wafer.ai/pass",- credential_attr="wafer_api_key",- default_base_url=WAFER_DEFAULT_BASE,- proxy_attr="wafer_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "native_anthropic"),- ),- "lmstudio": ProviderDescriptor(- provider_id="lmstudio",- transport_type="anthropic_messages",- static_credential="lm-studio",- default_base_url=LMSTUDIO_DEFAULT_BASE,- base_url_attr="lm_studio_base_url",- proxy_attr="lmstudio_proxy",- capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),+ "cerebras": ProviderDescriptor(+ provider_id="cerebras",+ transport_type="openai_chat",+ credential_env="CEREBRAS_API_KEY",+ credential_url="https://cloud.cerebras.ai",+ credential_attr="cerebras_api_key",+ default_base_url=CEREBRAS_DEFAULT_BASE,+ proxy_attr="cerebras_proxy",+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),),- "llamacpp": ProviderDescriptor(- provider_id="llamacpp",- transport_type="anthropic_messages",- static_credential="llamacpp",- default_base_url=LLAMACPP_DEFAULT_BASE,- base_url_attr="llamacpp_base_url",- proxy_attr="llamacpp_proxy",- capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),+ "groq": ProviderDescriptor(+ provider_id="groq",+ transport_type="openai_chat",+ credential_env="GROQ_API_KEY",+ credential_url="https://console.groq.com/keys",+ credential_attr="groq_api_key",+ default_base_url=GROQ_DEFAULT_BASE,+ proxy_attr="groq_proxy",+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),),- "ollama": ProviderDescriptor(- provider_id="ollama",+ "fireworks": ProviderDescriptor(+ provider_id="fireworks",transport_type="anthropic_messages",- static_credential="ollama",- default_base_url=OLLAMA_DEFAULT_BASE,- base_url_attr="ollama_base_url",+ credential_env="FIREWORKS_API_KEY",+ credential_url="https://fireworks.ai/account/api-keys",+ credential_attr="fireworks_api_key",+ default_base_url=FIREWORKS_DEFAULT_BASE,+ proxy_attr="fireworks_proxy",capabilities=("chat","streaming","tools","thinking","native_anthropic",- "local",+ "rate_limit",),),- "opencode": ProviderDescriptor(- provider_id="opencode",- transport_type="openai_chat",- credential_env="OPENCODE_API_KEY",- credential_url="https://opencode.ai/auth",- credential_attr="opencode_api_key",- default_base_url=OPENCODE_DEFAULT_BASE,- proxy_attr="opencode_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),- ),- "opencode_go": ProviderDescriptor(- provider_id="opencode_go",- transport_type="openai_chat",- credential_env="OPENCODE_API_KEY",- credential_url="https://opencode.ai/auth",- credential_attr="opencode_api_key",- default_base_url=OPENCODE_GO_DEFAULT_BASE,- proxy_attr="opencode_go_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),- ),"zai": ProviderDescriptor(provider_id="zai",transport_type="anthropic_messages",@@ -199,56 +213,46 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {"rate_limit",),),- "fireworks": ProviderDescriptor(- provider_id="fireworks",+ "lmstudio": ProviderDescriptor(+ provider_id="lmstudio",transport_type="anthropic_messages",- credential_env="FIREWORKS_API_KEY",- credential_url="https://fireworks.ai/account/api-keys",- credential_attr="fireworks_api_key",- default_base_url=FIREWORKS_DEFAULT_BASE,- proxy_attr="fireworks_proxy",+ static_credential="lm-studio",+ default_base_url=LMSTUDIO_DEFAULT_BASE,+ base_url_attr="lm_studio_base_url",+ proxy_attr="lmstudio_proxy",+ capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),+ ),+ "llamacpp": ProviderDescriptor(+ provider_id="llamacpp",+ transport_type="anthropic_messages",+ static_credential="llamacpp",+ default_base_url=LLAMACPP_DEFAULT_BASE,+ base_url_attr="llamacpp_base_url",+ proxy_attr="llamacpp_proxy",+ capabilities=("chat", "streaming", "tools", "native_anthropic", "local"),+ ),+ "ollama": ProviderDescriptor(+ provider_id="ollama",+ transport_type="anthropic_messages",+ static_credential="ollama",+ default_base_url=OLLAMA_DEFAULT_BASE,+ base_url_attr="ollama_base_url",capabilities=("chat","streaming","tools","thinking","native_anthropic",- "rate_limit",+ "local",),),- "gemini": ProviderDescriptor(- provider_id="gemini",- transport_type="openai_chat",- credential_env="GEMINI_API_KEY",- credential_url="https://aistudio.google.com/apikey",- credential_attr="gemini_api_key",- default_base_url=GEMINI_DEFAULT_BASE,- proxy_attr="gemini_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),- ),- "groq": ProviderDescriptor(- provider_id="groq",- transport_type="openai_chat",- credential_env="GROQ_API_KEY",- credential_url="https://console.groq.com/keys",- credential_attr="groq_api_key",- default_base_url=GROQ_DEFAULT_BASE,- proxy_attr="groq_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),- ),- "cerebras": ProviderDescriptor(- provider_id="cerebras",- transport_type="openai_chat",- credential_env="CEREBRAS_API_KEY",- credential_url="https://cloud.cerebras.ai",- credential_attr="cerebras_api_key",- default_base_url=CEREBRAS_DEFAULT_BASE,- proxy_attr="cerebras_proxy",- capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),- ),}-# Order matches docs / historical error text; must match PROVIDER_CATALOG keys.+# Key order:+# NVIDIA NIM first (README default), DeepSeek fourth, Wafer ninth / Kimi tenth; then cerebras /+# groq / fireworks overlap; remainder and locals last per project plan (+# github.com/cheahjs/free-llm-api-resources Free Providers TOC as rough guide beyond fixed slots).+# ``SUPPORTED_PROVIDER_IDS`` inherits this insertion order for UI and error-message listing.SUPPORTED_PROVIDER_IDS: tuple[str, ...] = tuple(PROVIDER_CATALOG.keys())if len(set(SUPPORTED_PROVIDER_IDS)) != len(SUPPORTED_PROVIDER_IDS):diff --git a/providers/registry.py b/providers/registry.pyindex 34cb19a2..040869a4 100644--- a/providers/registry.py+++ b/providers/registry.py@@ -139,21 +139,21 @@ def _create_cerebras(config: ProviderConfig, _settings: Settings) -> BaseProvidePROVIDER_FACTORIES: dict[str, ProviderFactory] = {"nvidia_nim": _create_nvidia_nim,"open_router": _create_open_router,+ "gemini": _create_gemini,+ "deepseek": _create_deepseek,"mistral": _create_mistral,"mistral_codestral": _create_mistral_codestral,- "deepseek": _create_deepseek,- "lmstudio": _create_lmstudio,- "llamacpp": _create_llamacpp,- "ollama": _create_ollama,- "kimi": _create_kimi,- "wafer": _create_wafer,"opencode": _create_opencode,"opencode_go": _create_opencode_go,- "zai": _create_zai,- "fireworks": _create_fireworks,- "gemini": _create_gemini,- "groq": _create_groq,+ "wafer": _create_wafer,+ "kimi": _create_kimi,"cerebras": _create_cerebras,+ "groq": _create_groq,+ "fireworks": _create_fireworks,+ "zai": _create_zai,+ "lmstudio": _create_lmstudio,+ "llamacpp": _create_llamacpp,+ "ollama": _create_ollama,}if set(PROVIDER_DESCRIPTORS) != set(SUPPORTED_PROVIDER_IDS) or set(diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.pynew file mode 100644index 00000000..73412581--- /dev/null+++ b/tests/contracts/test_provider_catalog_order.py@@ -0,0 +1,32 @@+"""Freeze ``PROVIDER_CATALOG`` insertion order used as canonical provider ranking."""++from __future__ import annotations++from config.provider_catalog import PROVIDER_CATALOG, SUPPORTED_PROVIDER_IDS++_EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (+ "nvidia_nim",+ "open_router",+ "gemini",+ "deepseek",+ "mistral",+ "mistral_codestral",+ "opencode",+ "opencode_go",+ "wafer",+ "kimi",+ "cerebras",+ "groq",+ "fireworks",+ "zai",+ "lmstudio",+ "llamacpp",+ "ollama",+)+++def test_provider_catalog_key_order_matches_canonical_plan() -> None:+ """NIM first; DeepSeek fourth; Wafer ninth / Kimi tenth (see contributor plan)."""++ assert tuple(PROVIDER_CATALOG.keys()) == _EXPECTED_PROVIDER_ORDER+ assert SUPPORTED_PROVIDER_IDS == _EXPECTED_PROVIDER_ORDER