Skip to content

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.example
index 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.md
index 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.firew
Browse 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](http
Browse 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 `cerebr
Cerebras 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 Tier
Each 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.py
index 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.py
index 34cb19a2..040869a4 100644
--- a/providers/registry.py
+++ b/providers/registry.py
@@ -139,21 +139,21 @@ def _create_cerebras(config: ProviderConfig, _settings: Settings) -> BaseProvide
PROVIDER_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.py
new file mode 100644
index 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