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

Add Cloudflare provider (#933)

Ali Khokhar478e96655c5c
diff --git a/.env.example b/.env.example
index 8f830f1f..dc3edae6 100644
--- a/.env.example
+++ b/.env.example
@@ -38,6 +38,11 @@ ZAI_API_KEY=""
FIREWORKS_API_KEY=""
+# Cloudflare AI REST Config (Anthropic-compatible Messages at api.cloudflare.com/client/v4/accounts/<id>/ai/v1)
+CLOUDFLARE_API_TOKEN=""
+CLOUDFLARE_ACCOUNT_ID=""
+
+
# Gemini / Google AI Studio (OpenAI-compatible Chat Completions; see https://ai.google.dev/gemini-api/docs/openai)
GEMINI_API_KEY=""
@@ -64,7 +69,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" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "wafer" | "kimi" | "cerebras" | "groq" | "fireworks" | "zai" | "lmstudio" | "llamacpp" | "ollama"
+# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "wafer" | "kimi" | "cerebras" | "groq" | "fireworks" | "cloudflare" | "zai" | "lmstudio" | "llamacpp" | "ollama"
MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
@@ -87,6 +92,7 @@ FCC_SMOKE_MODEL_OPENCODE=
FCC_SMOKE_MODEL_OPENCODE_GO=
FCC_SMOKE_MODEL_ZAI=
FCC_SMOKE_MODEL_FIREWORKS=
+FCC_SMOKE_MODEL_CLOUDFLARE=
FCC_SMOKE_MODEL_GEMINI=
FCC_SMOKE_MODEL_GROQ=
FCC_SMOKE_MODEL_CEREBRAS=
@@ -119,6 +125,7 @@ OPENCODE_PROXY=""
OPENCODE_GO_PROXY=""
ZAI_PROXY=""
FIREWORKS_PROXY=""
+CLOUDFLARE_PROXY=""
GEMINI_PROXY=""
GROQ_PROXY=""
CEREBRAS_PROXY=""
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 1f9647c1..d0836e38 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -357,16 +357,19 @@ DeepSeek attachment/tool/thinking compatibility.
Shared provider responsibilities include upstream rate limiting, model listing,
safe error mapping, transport cleanup, thinking/tool handling, retry or recovery
where supported, and returning Anthropic SSE strings to the service layer.
+Provider-specific inputs that do not apply to other upstreams, such as
+Cloudflare's account ID, stay in that provider's factory/client instead of being
+added to shared `ProviderConfig`.
### Adding A Provider
1. Add provider metadata to [config/provider_catalog.py](config/provider_catalog.py).
2. Add credentials and related settings to [config/settings.py](config/settings.py)
and [.env.example](.env.example) when user configurable.
-3. Add provider metadata to [config/provider_catalog.py](config/provider_catalog.py);
- Admin UI provider fields are generated from the catalog. Add admin-only help
- text under [api/admin_config/](api/admin_config/) only when the generated
- labels/descriptions are insufficient.
+3. Let Admin UI provider credential, local URL, and proxy fields come from the
+ catalog. Add admin-only help text or provider-specific fields under
+ [api/admin_config/](api/admin_config/) only when the generated manifest is
+ insufficient.
4. Implement the provider under [providers/](providers/) using the appropriate
shared transport family.
5. Add a factory in [providers/runtime/factory.py](providers/runtime/factory.py).
diff --git a/README.md b/README.md
index c36107a6..9d74b84b 100644
--- a/README.md
+++ b/README.md
@@ -57,7 +57,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code (CLI and
- Drop-in proxy for Claude Code's Anthropic API calls (`/v1/messages`, `/v1/models`).
- Drop-in proxy for Codex via the OpenAI Responses API (`/v1/responses`).
- `fcc-claude` and `fcc-codex` launchers that read the current Admin UI port and auth token each time they start.
-- 17 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.
+- 18 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, Cloudflare, Z.ai, LM Studio, llama.cpp, and Ollama.
- Per-model routing for Claude Code: send Opus, Sonnet, Haiku, and fallback traffic to different providers.
- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (see [Model Picker](#model-picker)).
- Native Codex `/model` picker support when launched through `fcc-codex`, using a generated local model catalog.
@@ -306,7 +306,15 @@ Fireworks exposes an **Anthropic-compatible** Messages API at `https://api.firew
Browse models at [fireworks.ai/models](https://fireworks.ai/models).
-### 14. [Z.ai](https://z.ai/)
+### 14. [Cloudflare](https://developers.cloudflare.com/ai-gateway/)
+
+Create a Cloudflare API token and copy your account ID from the Cloudflare dashboard.
+
+In the Admin UI, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`, then set `MODEL` to a Cloudflare model slug such as `cloudflare/anthropic/claude-sonnet-4-5`.
+
+This provider calls Cloudflare's account-scoped **Anthropic-compatible** Messages API at `https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1/messages`. The first Cloudflare integration targets third-party Anthropic-compatible models; Cloudflare AI Gateway BYOK/provider-gateway routing is not required.
+
+### 15. [Z.ai](https://z.ai/)
Get an API key at [Z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).
@@ -321,13 +329,13 @@ Popular examples:
Browse models at [Z.ai](https://z.ai).
-### 15. [LM Studio](https://lmstudio.ai/)
+### 16. [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)
+### 17. [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.
@@ -335,7 +343,7 @@ In the Admin UI, keep or update `LLAMACPP_BASE_URL`, then set `MODEL` to the loc
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/)
+### 18. [Ollama](https://ollama.com/)
Run Ollama and pull a model:
@@ -563,7 +571,7 @@ Important pieces:
- `fcc-codex` registers a custom `fcc` provider that points Codex at the local proxy's `/v1/responses` endpoint.
- Model routing resolves Claude model names to `MODEL_OPUS`, `MODEL_SONNET`, `MODEL_HAIKU`, or `MODEL`.
- NIM, OpenCode Zen, and OpenCode Go use OpenAI chat streaming translated into Anthropic SSE.
-- Wafer, OpenRouter, DeepSeek, Kimi, Fireworks AI, Z.ai, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports where applicable (with provider-specific quirks and model-list URLs).
+- Wafer, OpenRouter, DeepSeek, Kimi, Fireworks AI, Cloudflare, Z.ai, LM Studio, llama.cpp, and Ollama use Anthropic Messages style transports where applicable (with provider-specific quirks and model-list URLs).
- The proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape each client expects.
- Request optimizations answer trivial Claude Code probes locally to save latency and quota.
diff --git a/api/admin_config/manifest.py b/api/admin_config/manifest.py
index 7fbb5208..b257ce14 100644
--- a/api/admin_config/manifest.py
+++ b/api/admin_config/manifest.py
@@ -573,6 +573,12 @@ _NON_PROVIDER_FIELDS: tuple[ConfigFieldSpec, ...] = (
"smoke",
advanced=True,
),
+ ConfigFieldSpec(
+ "FCC_SMOKE_MODEL_CLOUDFLARE",
+ "Smoke Cloudflare Model",
+ "smoke",
+ advanced=True,
+ ),
ConfigFieldSpec(
"FCC_SMOKE_MODEL_GEMINI",
"Smoke Gemini Model",
diff --git a/api/admin_config/provider_manifest.py b/api/admin_config/provider_manifest.py
index eceb11a3..473b02e3 100644
--- a/api/admin_config/provider_manifest.py
+++ b/api/admin_config/provider_manifest.py
@@ -40,6 +40,13 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
"label": "Fireworks API Key",
"description": "Fireworks AI inference API key.",
},
+ "CLOUDFLARE_API_TOKEN": {
+ "label": "Cloudflare API Token",
+ "description": (
+ "Cloudflare API token for account-scoped AI REST requests. "
+ "Use with CLOUDFLARE_ACCOUNT_ID."
+ ),
+ },
"GEMINI_API_KEY": {
"label": "Gemini API Key",
"description": (
@@ -73,6 +80,7 @@ def provider_field_specs() -> tuple[dict[str, Any], ...]:
return (
*_credential_field_specs(),
+ *_cloudflare_account_field_specs(),
*_local_base_url_field_specs(),
*_proxy_field_specs(),
)
@@ -117,6 +125,20 @@ def _local_base_url_field_specs() -> tuple[dict[str, Any], ...]:
return tuple(specs)
+def _cloudflare_account_field_specs() -> tuple[dict[str, Any], ...]:
+ return (
+ {
+ "key": "CLOUDFLARE_ACCOUNT_ID",
+ "label": "Cloudflare Account ID",
+ "section_id": "providers",
+ "settings_attr": "cloudflare_account_id",
+ "description": (
+ "Cloudflare account ID used to build the /accounts/{id}/ai/v1 endpoint."
+ ),
+ },
+ )
+
+
def _proxy_field_specs() -> tuple[dict[str, Any], ...]:
specs: list[dict[str, Any]] = []
for descriptor in PROVIDER_CATALOG.values():
diff --git a/config/provider_catalog.py b/config/provider_catalog.py
index 424ffd62..5808c050 100644
--- a/config/provider_catalog.py
+++ b/config/provider_catalog.py
@@ -21,6 +21,8 @@ DEEPSEEK_ANTHROPIC_DEFAULT_BASE = "https://api.deepseek.com/anthropic"
# Historical export name: DeepSeek upstream is the native Anthropic path above.
DEEPSEEK_DEFAULT_BASE = DEEPSEEK_ANTHROPIC_DEFAULT_BASE
FIREWORKS_DEFAULT_BASE = "https://api.fireworks.ai/inference/v1"
+# Cloudflare account-scoped AI REST root; provider appends /accounts/{id}/ai/v1.
+CLOUDFLARE_AI_REST_ROOT = "https://api.cloudflare.com/client/v4"
OPENROUTER_DEFAULT_BASE = "https://openrouter.ai/api/v1"
MISTRAL_DEFAULT_BASE = "https://api.mistral.ai/v1"
# Codestral IDE/personal endpoint (distinct from La Plateforme ``api.mistral.ai`` keys).
@@ -211,6 +213,24 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
"rate_limit",
),
),
+ "cloudflare": ProviderDescriptor(
+ provider_id="cloudflare",
+ display_name="Cloudflare",
+ transport_type="anthropic_messages",
+ credential_env="CLOUDFLARE_API_TOKEN",
+ credential_url="https://dash.cloudflare.com/profile/api-tokens",
+ credential_attr="cloudflare_api_token",
+ default_base_url=CLOUDFLARE_AI_REST_ROOT,
+ proxy_attr="cloudflare_proxy",
+ capabilities=(
+ "chat",
+ "streaming",
+ "tools",
+ "thinking",
+ "native_anthropic",
+ "rate_limit",
+ ),
+ ),
"zai": ProviderDescriptor(
provider_id="zai",
display_name="Z.ai",
@@ -268,7 +288,7 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
# 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 (
+# groq / fireworks / Cloudflare 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())
diff --git a/config/settings.py b/config/settings.py
index 90a6a3e3..a463e57e 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -47,6 +47,14 @@ class Settings(BaseSettings):
# ==================== Fireworks AI Config ====================
fireworks_api_key: str = Field(default="", validation_alias="FIREWORKS_API_KEY")
+ # ==================== Cloudflare AI REST Config ====================
+ cloudflare_api_token: str = Field(
+ default="", validation_alias="CLOUDFLARE_API_TOKEN"
+ )
+ cloudflare_account_id: str = Field(
+ default="", validation_alias="CLOUDFLARE_ACCOUNT_ID"
+ )
+
# ==================== Google Gemini (Google AI Studio) ====================
gemini_api_key: str = Field(default="", validation_alias="GEMINI_API_KEY")
@@ -113,6 +121,7 @@ class Settings(BaseSettings):
opencode_go_proxy: str = Field(default="", validation_alias="OPENCODE_GO_PROXY")
zai_proxy: str = Field(default="", validation_alias="ZAI_PROXY")
fireworks_proxy: str = Field(default="", validation_alias="FIREWORKS_PROXY")
+ cloudflare_proxy: str = Field(default="", validation_alias="CLOUDFLARE_PROXY")
gemini_proxy: str = Field(default="", validation_alias="GEMINI_PROXY")
groq_proxy: str = Field(default="", validation_alias="GROQ_PROXY")
cerebras_proxy: str = Field(default="", validation_alias="CEREBRAS_PROXY")
diff --git a/providers/cloudflare/__init__.py b/providers/cloudflare/__init__.py
new file mode 100644
index 00000000..242622d7
--- /dev/null
+++ b/providers/cloudflare/__init__.py
@@ -0,0 +1,13 @@
+"""Cloudflare AI REST provider package."""
+
+from .client import (
+ CLOUDFLARE_AI_REST_ROOT,
+ CloudflareProvider,
+ cloudflare_ai_base_url,
+)
+
+__all__ = (
+ "CLOUDFLARE_AI_REST_ROOT",
+ "CloudflareProvider",
+ "cloudflare_ai_base_url",
+)
diff --git a/providers/cloudflare/client.py b/providers/cloudflare/client.py
new file mode 100644
index 00000000..b3c8af66
--- /dev/null
+++ b/providers/cloudflare/client.py
@@ -0,0 +1,93 @@
+"""Cloudflare AI REST provider using Anthropic-compatible Messages."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from providers.base import ProviderConfig
+from providers.defaults import CLOUDFLARE_AI_REST_ROOT
+from providers.exceptions import AuthenticationError
+from providers.transports.anthropic_messages import (
+ AnthropicMessagesTransport,
+ NativeMessagesRequestPolicy,
+ build_native_messages_request_body,
+)
+
+_ANTHROPIC_VERSION = "2023-06-01"
+_REQUEST_POLICY = NativeMessagesRequestPolicy(
+ provider_name="CLOUDFLARE",
+ extra_body="reject",
+ reject_extra_body_message=(
+ "Cloudflare native Messages API does not support extra_body on requests."
+ ),
+)
+
+
+def cloudflare_ai_base_url(api_root: str | None, account_id: str) -> str:
+ """Return the account-scoped Cloudflare AI REST base URL."""
+
+ return f"{_cloudflare_account_api_url(api_root, account_id)}/ai/v1"
+
+
+def _cloudflare_model_search_url(api_root: str | None, account_id: str) -> str:
+ """Return the Cloudflare account model-search endpoint URL."""
+
+ return f"{_cloudflare_account_api_url(api_root, account_id)}/ai/models/search"
+
+
+def _cloudflare_account_api_url(api_root: str | None, account_id: str) -> str:
+ """Return the account-scoped Cloudflare API root URL."""
+
+ stripped_account = account_id.strip()
+ if not stripped_account:
+ raise AuthenticationError(
+ "CLOUDFLARE_ACCOUNT_ID is not set. Add it to your .env file."
+ )
+ root = (api_root or CLOUDFLARE_AI_REST_ROOT).rstrip("/")
+ encoded_account = quote(stripped_account, safe="")
+ return f"{root}/accounts/{encoded_account}"
+
+
+class CloudflareProvider(AnthropicMessagesTransport):
+ """Cloudflare account-scoped AI REST provider."""
+
+ def __init__(self, config: ProviderConfig, *, account_id: str):
+ base_url = cloudflare_ai_base_url(config.base_url, account_id)
+ self._model_search_url = _cloudflare_model_search_url(
+ config.base_url, account_id
+ )
+ super().__init__(
+ config.model_copy(update={"base_url": base_url}),
+ provider_name="CLOUDFLARE",
+ default_base_url=base_url,
+ )
+
+ def _build_request_body(
+ self, request: Any, thinking_enabled: bool | None = None
+ ) -> dict:
+ return build_native_messages_request_body(
+ request,
+ thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+ policy=_REQUEST_POLICY,
+ )
+
+ def _request_headers(self) -> dict[str, str]:
+ return {
+ "Accept": "text/event-stream",
+ "Authorization": f"Bearer {self._api_key}",
+ "Content-Type": "application/json",
+ "anthropic-version": _ANTHROPIC_VERSION,
+ }
+
+ def _model_list_headers(self) -> dict[str, str]:
+ return {"Authorization": f"Bearer {self._api_key}"}
+
+ async def _send_model_list_request(self) -> httpx.Response:
+ return await self._client.get(
+ self._model_search_url,
+ params={"format": "openrouter"},
+ headers=self._model_list_headers(),
+ )
diff --git a/providers/defaults.py b/providers/defaults.py
index 255d8a8c..2d2af230 100644
--- a/providers/defaults.py
+++ b/providers/defaults.py
@@ -2,6 +2,7 @@
from config.provider_catalog import (
CEREBRAS_DEFAULT_BASE,
+ CLOUDFLARE_AI_REST_ROOT,
CODESTRAL_DEFAULT_BASE,
DEEPSEEK_ANTHROPIC_DEFAULT_BASE,
DEEPSEEK_DEFAULT_BASE,
@@ -22,6 +23,7 @@ from config.provider_catalog import (
__all__ = (
"CEREBRAS_DEFAULT_BASE",
+ "CLOUDFLARE_AI_REST_ROOT",
"CODESTRAL_DEFAULT_BASE",
"DEEPSEEK_ANTHROPIC_DEFAULT_BASE",
"DEEPSEEK_DEFAULT_BASE",
diff --git a/providers/runtime/factory.py b/providers/runtime/factory.py
index 9211eb2f..8a1d9914 100644
--- a/providers/runtime/factory.py
+++ b/providers/runtime/factory.py
@@ -103,6 +103,12 @@ def _create_fireworks(config: ProviderConfig, _settings: Settings) -> BaseProvid
return FireworksProvider(config)
+def _create_cloudflare(config: ProviderConfig, settings: Settings) -> BaseProvider:
+ from providers.cloudflare import CloudflareProvider
+
+ return CloudflareProvider(config, account_id=settings.cloudflare_account_id)
+
+
def _create_gemini(config: ProviderConfig, _settings: Settings) -> BaseProvider:
from providers.gemini import GeminiProvider
@@ -135,6 +141,7 @@ PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"cerebras": _create_cerebras,
"groq": _create_groq,
"fireworks": _create_fireworks,
+ "cloudflare": _create_cloudflare,
"zai": _create_zai,
"lmstudio": _create_lmstudio,
"llamacpp": _create_llamacpp,
diff --git a/pyproject.toml b/pyproject.toml
index 2dc4830f..ae1c1094 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "2.3.23"
+version = "2.4.0"
description = "Middleware between Claude Code CLI (Anthropic API) and NVIDIA NIM"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/README.md b/smoke/README.md
index a2d73f03..810b7566 100644
--- a/smoke/README.md
+++ b/smoke/README.md
@@ -130,8 +130,8 @@ uv run pytest smoke/product -n 0 -s --tb=short
`FCC_SMOKE_MODEL_MISTRAL`, `FCC_SMOKE_MODEL_MISTRAL_CODESTRAL`,
`FCC_SMOKE_MODEL_DEEPSEEK`, `FCC_SMOKE_MODEL_KIMI`,
`FCC_SMOKE_MODEL_WAFER`, `FCC_SMOKE_MODEL_OPENCODE`, `FCC_SMOKE_MODEL_OPENCODE_GO`,
- `FCC_SMOKE_MODEL_ZAI`, `FCC_SMOKE_MODEL_FIREWORKS`, `FCC_SMOKE_MODEL_GEMINI`,
- `FCC_SMOKE_MODEL_GROQ`, `FCC_SMOKE_MODEL_CEREBRAS`,
+ `FCC_SMOKE_MODEL_ZAI`, `FCC_SMOKE_MODEL_FIREWORKS`, `FCC_SMOKE_MODEL_CLOUDFLARE`,
+ `FCC_SMOKE_MODEL_GEMINI`, `FCC_SMOKE_MODEL_GROQ`, `FCC_SMOKE_MODEL_CEREBRAS`,
`FCC_SMOKE_MODEL_LMSTUDIO`,
`FCC_SMOKE_MODEL_LLAMACPP`, `FCC_SMOKE_MODEL_OLLAMA`: optional per-provider
smoke model overrides. Values may include the provider prefix or just the model
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 571e559b..c428039a 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -58,6 +58,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"gemini": "gemini/models/gemini-3.1-flash-lite",
"groq": "groq/llama-3.3-70b-versatile",
"cerebras": "cerebras/llama3.1-8b",
+ "cloudflare": "cloudflare/anthropic/claude-sonnet-4-5",
}
NVIDIA_NIM_CLI_DEFAULT_MODELS: tuple[str, ...] = (
@@ -258,6 +259,11 @@ class SmokeConfig:
return bool(self.settings.groq_api_key.strip())
if provider == "cerebras":
return bool(self.settings.cerebras_api_key.strip())
+ if provider == "cloudflare":
+ return bool(
+ self.settings.cloudflare_api_token.strip()
+ and self.settings.cloudflare_account_id.strip()
+ )
return False
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 8b5789c4..b132cfab 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -29,6 +29,8 @@ def _clear_process_config(monkeypatch) -> None:
"OPENROUTER_API_KEY",
"ANTHROPIC_AUTH_TOKEN",
"FCC_ENV_FILE",
+ "CLOUDFLARE_API_TOKEN",
+ "CLOUDFLARE_ACCOUNT_ID",
"HOST",
"PORT",
"LOG_FILE",
@@ -103,6 +105,8 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
assert "ANTHROPIC_AUTH_TOKEN" in keys
assert "OPENROUTER_API_KEY" in keys
assert "FIREWORKS_API_KEY" in keys
+ assert "CLOUDFLARE_API_TOKEN" in keys
+ assert "CLOUDFLARE_ACCOUNT_ID" in keys
assert "GEMINI_API_KEY" in keys
assert "GROQ_API_KEY" in keys
assert "CEREBRAS_API_KEY" in keys
@@ -285,6 +289,34 @@ def test_admin_apply_writes_cerebras_key_and_masks_preview(monkeypatch, tmp_path
assert "CEREBRAS_API_KEY=cb-secret" in text
+def test_admin_apply_writes_cloudflare_fields_and_masks_preview(monkeypatch, tmp_path):
+ _set_home(monkeypatch, tmp_path)
+ _clear_process_config(monkeypatch)
+ app = create_app(lifespan_enabled=False)
+
+ response = _local_client(app).post(
+ "/admin/api/config/apply",
+ json={
+ "values": {
+ "MODEL": "cloudflare/anthropic/claude-sonnet-4-5",
+ "CLOUDFLARE_API_TOKEN": "cf-secret",
+ "CLOUDFLARE_ACCOUNT_ID": "cf-account",
+ }
+ },
+ )
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body["applied"] is True
+ assert "CLOUDFLARE_API_TOKEN=********" in body["env_preview"]
+ assert "CLOUDFLARE_ACCOUNT_ID=cf-account" in body["env_preview"]
+ env_file = tmp_path / ".fcc" / ".env"
+ text = env_file.read_text(encoding="utf-8")
+ assert "MODEL=cloudflare/anthropic/claude-sonnet-4-5" in text
+ assert "CLOUDFLARE_API_TOKEN=cf-secret" in text
+ assert "CLOUDFLARE_ACCOUNT_ID=cf-account" in text
+
+
def test_admin_apply_preserves_hidden_diagnostics_and_smoke_values(
monkeypatch, tmp_path
):
diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.py
index 0691cca2..1aeb17af 100644
--- a/tests/api/test_dependencies.py
+++ b/tests/api/test_dependencies.py
@@ -52,6 +52,9 @@ def _make_mock_settings(**overrides):
mock.zai_proxy = ""
mock.fireworks_api_key = ""
mock.fireworks_proxy = ""
+ mock.cloudflare_api_token = ""
+ mock.cloudflare_account_id = ""
+ mock.cloudflare_proxy = ""
mock.gemini_api_key = ""
mock.gemini_proxy = ""
mock.groq_api_key = ""
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index f8bb7f81..994ae84b 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -284,6 +284,18 @@ class TestSettings:
settings = Settings()
assert settings.wafer_api_key == "wafer-key"
+ def test_cloudflare_settings_from_env(self, monkeypatch):
+ """Cloudflare token, account, and proxy env vars load into settings."""
+ from config.settings import Settings
+
+ monkeypatch.setenv("CLOUDFLARE_API_TOKEN", "cf-token")
+ monkeypatch.setenv("CLOUDFLARE_ACCOUNT_ID", "cf-account")
+ monkeypatch.setenv("CLOUDFLARE_PROXY", "http://proxy.test:8080")
+ settings = Settings()
+ assert settings.cloudflare_api_token == "cf-token"
+ assert settings.cloudflare_account_id == "cf-account"
+ assert settings.cloudflare_proxy == "http://proxy.test:8080"
+
def test_per_model_thinking_from_env(self, monkeypatch):
"""Per-model thinking env vars are loaded into settings."""
from config.settings import Settings
@@ -671,6 +683,11 @@ class TestPerModelMapping:
),
({"MODEL": "deepseek/deepseek-chat"}, "deepseek/deepseek-chat", None),
({"MODEL": "wafer/DeepSeek-V4-Pro"}, "wafer/DeepSeek-V4-Pro", None),
+ (
+ {"MODEL": "cloudflare/anthropic/claude-sonnet-4-5"},
+ "cloudflare/anthropic/claude-sonnet-4-5",
+ None,
+ ),
({"MODEL": "lmstudio/qwen2.5-7b"}, "lmstudio/qwen2.5-7b", None),
({"MODEL": "llamacpp/local-model"}, "llamacpp/local-model", None),
({"MODEL": "ollama/llama3.1"}, "ollama/llama3.1", None),
@@ -852,6 +869,10 @@ class TestPerModelMapping:
assert parse_provider_type("llamacpp/model") == "llamacpp"
assert parse_provider_type("ollama/llama3.1") == "ollama"
assert parse_provider_type("wafer/DeepSeek-V4-Pro") == "wafer"
+ assert (
+ parse_provider_type("cloudflare/anthropic/claude-sonnet-4-5")
+ == "cloudflare"
+ )
assert parse_provider_type("gemini/models/gemini-3.1-flash-lite") == "gemini"
assert parse_provider_type("groq/llama-3.3-70b-versatile") == "groq"
assert parse_provider_type("cerebras/llama3.1-8b") == "cerebras"
@@ -871,6 +892,10 @@ class TestPerModelMapping:
assert parse_model_name("llamacpp/model") == "model"
assert parse_model_name("ollama/llama3.1") == "llama3.1"
assert parse_model_name("wafer/DeepSeek-V4-Pro") == "DeepSeek-V4-Pro"
+ assert (
+ parse_model_name("cloudflare/anthropic/claude-sonnet-4-5")
+ == "anthropic/claude-sonnet-4-5"
+ )
assert (
parse_model_name("gemini/models/gemini-3.1-flash-lite")
== "models/gemini-3.1-flash-lite"
diff --git a/tests/contracts/test_admin_provider_manifest.py b/tests/contracts/test_admin_provider_manifest.py
index 8eb76bda..74e4f450 100644
--- a/tests/contracts/test_admin_provider_manifest.py
+++ b/tests/contracts/test_admin_provider_manifest.py
@@ -107,3 +107,11 @@ def test_provider_catalog_display_names_are_admin_status_source() -> None:
assert set(status_by_provider) == set(PROVIDER_CATALOG)
for provider_id, desc in PROVIDER_CATALOG.items():
assert status_by_provider[provider_id]["display_name"] == desc.display_name
+
+
+def test_cloudflare_account_id_is_admin_provider_field() -> None:
+ entry = FIELD_BY_KEY["CLOUDFLARE_ACCOUNT_ID"]
+
+ assert entry.settings_attr == "cloudflare_account_id"
+ assert entry.section_id == "providers"
+ assert entry.secret is False
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index 3e1c5416..854d2aa4 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -6,6 +6,7 @@ from pathlib import Path
from messaging.platforms.factory import create_messaging_components
from providers.base import BaseProvider
from providers.cerebras import CerebrasProvider
+from providers.cloudflare import CloudflareProvider
from providers.codestral import CodestralProvider
from providers.deepseek import DeepSeekProvider
from providers.fireworks import FireworksProvider
@@ -84,6 +85,7 @@ def test_provider_and_platform_registries_include_advertised_builtins() -> None:
"deepseek": DeepSeekProvider,
"kimi": KimiProvider,
"fireworks": FireworksProvider,
+ "cloudflare": CloudflareProvider,
"lmstudio": LMStudioProvider,
"llamacpp": LlamaCppProvider,
"ollama": OllamaProvider,
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 73412581..3cb12b86 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -18,6 +18,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"cerebras",
"groq",
"fireworks",
+ "cloudflare",
"zai",
"lmstudio",
"llamacpp",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index c57aa8b0..01e56c29 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -41,6 +41,8 @@ def _settings(**overrides):
"groq_api_key": "",
"cerebras_api_key": "",
"fireworks_api_key": "",
+ "cloudflare_api_token": "",
+ "cloudflare_account_id": "",
"lm_studio_base_url": "",
"llamacpp_base_url": "",
"ollama_base_url": "http://localhost:11434",
@@ -144,6 +146,37 @@ def test_wafer_provider_configuration_uses_api_key(monkeypatch) -> None:
assert models[0].full_model == PROVIDER_SMOKE_DEFAULT_MODELS["wafer"]
+def test_cloudflare_provider_configuration_requires_token_and_account(
+ monkeypatch,
+) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_CLOUDFLARE", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ cloudflare_api_token="cf-token",
+ cloudflare_account_id="cf-account",
+ )
+ )
+
+ assert config.has_provider_configuration("cloudflare")
+ models = config.provider_smoke_models()
+ assert models[0].provider == "cloudflare"
+ assert models[0].full_model == PROVIDER_SMOKE_DEFAULT_MODELS["cloudflare"]
+
+
+def test_cloudflare_provider_configuration_missing_account_is_unconfigured() -> None:
+ config = _smoke_config(
+ settings=_settings(
+ ollama_base_url="",
+ cloudflare_api_token="cf-token",
+ cloudflare_account_id="",
+ )
+ )
+
+ assert not config.has_provider_configuration("cloudflare")
+
+
def test_provider_smoke_model_override_accepts_model_name_without_prefix(
monkeypatch,
) -> None:
diff --git a/tests/providers/test_cloudflare.py b/tests/providers/test_cloudflare.py
new file mode 100644
index 00000000..9a0897c1
--- /dev/null
+++ b/tests/providers/test_cloudflare.py
@@ -0,0 +1,267 @@
+"""Tests for Cloudflare AI REST native Anthropic Messages provider."""
+
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+from api.models.anthropic import Message, MessagesRequest
+from core.anthropic.stream_contracts import parse_sse_text
+from providers.base import ProviderConfig
+from providers.cloudflare import (
+ CLOUDFLARE_AI_REST_ROOT,
+ CloudflareProvider,
+ cloudflare_ai_base_url,
+)
+from providers.exceptions import AuthenticationError, InvalidRequestError
+
+
+class FakeResponse:
+ def __init__(self, *, status_code: int = 200, lines: list[str] | None = None):
+ self.status_code = status_code
+ self._lines = lines or []
+ self.is_closed = False
+ self.headers = httpx.Headers()
+ self.request = httpx.Request("POST", f"{_BASE_URL}/messages")
+
+ async def aiter_lines(self):
+ for line in self._lines:
+ yield line
+
+ async def aiter_bytes(self, chunk_size: int = 65_536):
+ if False:
+ yield b""
+
+ async def aclose(self):
+ self.is_closed = True
+
+ def raise_for_status(self):
+ response = httpx.Response(self.status_code, request=self.request)
+ response.raise_for_status()
+
+
+_ACCOUNT_ID = "account-123"
+_BASE_URL = f"{CLOUDFLARE_AI_REST_ROOT}/accounts/{_ACCOUNT_ID}/ai/v1"
+_MODEL_SEARCH_URL = f"{CLOUDFLARE_AI_REST_ROOT}/accounts/{_ACCOUNT_ID}/ai/models/search"
+
+
+def cloudflare_config() -> ProviderConfig:
+ return ProviderConfig(
+ api_key="test-cloudflare-token",
+ base_url=CLOUDFLARE_AI_REST_ROOT,
+ rate_limit=10,
+ rate_window=60,
+ enable_thinking=True,
+ )
+
+
[email protected](autouse=True)
+def mock_rate_limiter():
+ @asynccontextmanager
+ async def _slot():
+ yield
+
+ with patch(
+ "providers.transports.anthropic_messages.transport.GlobalRateLimiter"
+ ) as mock:
+ instance = mock.get_scoped_instance.return_value
+
+ async def _passthrough(fn, *args, **kwargs):
+ return await fn(*args, **kwargs)
+
+ instance.execute_with_retry = AsyncMock(side_effect=_passthrough)
+ instance.concurrency_slot.side_effect = _slot
+ yield instance
+
+
+def cloudflare_provider(cloudflare_config: ProviderConfig) -> CloudflareProvider:
+ return CloudflareProvider(cloudflare_config, account_id=_ACCOUNT_ID)
+
+
+def test_cloudflare_ai_base_url_uses_account_scoped_messages_root() -> None:
+ assert cloudflare_ai_base_url(CLOUDFLARE_AI_REST_ROOT, "account/with slash") == (
+ f"{CLOUDFLARE_AI_REST_ROOT}/accounts/account%2Fwith%20slash/ai/v1"
+ )
+
+
+def test_missing_account_id_raises_authentication_error(
+ cloudflare_config: ProviderConfig,
+) -> None:
+ with pytest.raises(AuthenticationError, match="CLOUDFLARE_ACCOUNT_ID"):
+ CloudflareProvider(cloudflare_config, account_id=" ")
+
+
+def test_init_composes_account_scoped_base_url(
+ cloudflare_config: ProviderConfig,
+) -> None:
+ with patch("httpx.AsyncClient") as mock_client:
+ provider = CloudflareProvider(cloudflare_config, account_id=_ACCOUNT_ID)
+
+ assert provider._api_key == "test-cloudflare-token"
+ assert provider._base_url == _BASE_URL
+ assert provider._model_search_url == _MODEL_SEARCH_URL
+ assert provider._provider_name == "CLOUDFLARE"
+ assert mock_client.called
+
+
+def test_request_headers_use_bearer_auth(cloudflare_provider: CloudflareProvider):
+ headers = cloudflare_provider._request_headers()
+
+ assert headers["Authorization"] == "Bearer test-cloudflare-token"
+ assert headers["Accept"] == "text/event-stream"
+ assert headers["Content-Type"] == "application/json"
+ assert headers["anthropic-version"] == "2023-06-01"
+ assert "x-api-key" not in headers
+ assert cloudflare_provider._model_list_headers() == {
+ "Authorization": "Bearer test-cloudflare-token"
+ }
+
+
+def test_build_request_body_preserves_slash_model_id_and_forwards_thinking(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "anthropic/claude-sonnet-4-5",
+ "messages": [Message(role="user", content="Hello")],
+ "thinking": {"type": "enabled", "budget_tokens": 2048},
+ }
+ )
+
+ body = cloudflare_provider._build_request_body(request, thinking_enabled=True)
+
+ assert body["model"] == "anthropic/claude-sonnet-4-5"
+ assert body["stream"] is True
+ assert body["thinking"] == {"type": "enabled", "budget_tokens": 2048}
+
+
+def test_build_request_body_strips_prior_thinking_blocks_when_disabled(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "anthropic/claude-sonnet-4-5",
+ "messages": [
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "hidden"},
+ {"type": "text", "text": "visible"},
+ ],
+ },
+ {"role": "user", "content": "Continue"},
+ ],
+ }
+ )
+
+ body = cloudflare_provider._build_request_body(request, thinking_enabled=False)
+
+ assert body["messages"][0]["content"] == [{"type": "text", "text": "visible"}]
+
+
+def test_build_request_body_request_disabled_thinking_suppresses_thinking(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "anthropic/claude-sonnet-4-5",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "thinking": {"type": "disabled"},
+ }
+ )
+
+ body = cloudflare_provider._build_request_body(request, thinking_enabled=True)
+
+ assert "thinking" not in body
+
+
+def test_build_request_body_rejects_extra_body(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "anthropic/claude-sonnet-4-5",
+ "messages": [{"role": "user", "content": "Hello"}],
+ "extra_body": {"custom": True},
+ }
+ )
+
+ with pytest.raises(InvalidRequestError, match="does not support extra_body"):
+ cloudflare_provider._build_request_body(request)
+
+
+async def test_lists_models_from_cloudflare_model_search_endpoint(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ with patch.object(
+ cloudflare_provider._client,
+ "get",
+ new_callable=AsyncMock,
+ return_value=httpx.Response(
+ 200,
+ json={
+ "object": "list",
+ "data": [
+ {"id": "anthropic/claude-sonnet-4-5", "object": "model"},
+ {"id": "anthropic/claude-opus-4-5", "object": "model"},
+ ],
+ },
+ request=httpx.Request("GET", _MODEL_SEARCH_URL),
+ ),
+ ) as mock_get:
+ assert await cloudflare_provider.list_model_ids() == frozenset(
+ {"anthropic/claude-sonnet-4-5", "anthropic/claude-opus-4-5"}
+ )
+
+ mock_get.assert_awaited_once_with(
+ _MODEL_SEARCH_URL,
+ params={"format": "openrouter"},
+ headers={"Authorization": "Bearer test-cloudflare-token"},
+ )
+
+
+async def test_stream_uses_post_messages_path(
+ cloudflare_provider: CloudflareProvider,
+) -> None:
+ request = MessagesRequest(
+ model="anthropic/claude-sonnet-4-5",
+ messages=[Message(role="user", content="hi")],
+ )
+ response = FakeResponse(
+ lines=[
+ "event: message_start",
+ 'data: {"type":"message_start"}',
+ "",
+ "event: message_stop",
+ 'data: {"type":"message_stop"}',
+ "",
+ ]
+ )
+
+ with (
+ patch.object(
+ cloudflare_provider._client, "build_request", return_value=MagicMock()
+ ) as mock_build,
+ patch.object(
+ cloudflare_provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [event async for event in cloudflare_provider.stream_response(request)]
+
+ assert [event.event for event in parse_sse_text("".join(events))] == [
+ "message_start",
+ "message_stop",
+ ]
+ assert response.is_closed
+ assert mock_build.call_args.args[:2] == ("POST", "/messages")
+ assert mock_build.call_args.kwargs["headers"]["Authorization"] == (
+ "Bearer test-cloudflare-token"
+ )
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 424a0cbb..71e07e28 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -8,6 +8,7 @@ from config.nim import NimSettings
from config.provider_catalog import PROVIDER_CATALOG, ZAI_DEFAULT_BASE
from config.provider_ids import SUPPORTED_PROVIDER_IDS
from providers.cerebras import CerebrasProvider
+from providers.cloudflare import CloudflareProvider
from providers.codestral import CodestralProvider
from providers.deepseek import DeepSeekProvider
from providers.exceptions import UnknownProviderTypeError
@@ -58,6 +59,9 @@ def _make_settings(**overrides):
mock.zai_proxy = ""
mock.fireworks_proxy = ""
mock.fireworks_api_key = "test_fireworks_key"
+ mock.cloudflare_api_token = "test_cloudflare_token"
+ mock.cloudflare_account_id = "test_cloudflare_account"
+ mock.cloudflare_proxy = ""
mock.gemini_api_key = ""
mock.gemini_proxy = ""
mock.groq_api_key = ""
@@ -129,6 +133,31 @@ def test_zai_provider_config_ignores_stale_base_url_setting():
assert config.base_url == ZAI_DEFAULT_BASE
+def test_cloudflare_descriptor_uses_api_root_not_account_url():
+ descriptor = PROVIDER_CATALOG["cloudflare"]
+
+ assert descriptor.transport_type == "anthropic_messages"
+ assert descriptor.default_base_url == "https://api.cloudflare.com/client/v4"
+ assert descriptor.base_url_attr is None
+ assert "native_anthropic" in descriptor.capabilities
+ assert "thinking" in descriptor.capabilities
+
+
+def test_create_cloudflare_provider_uses_account_scoped_base_url():
+ settings = _make_settings(
+ cloudflare_api_token="test_cloudflare_token",
+ cloudflare_account_id="test-account",
+ )
+
+ with patch("httpx.AsyncClient"):
+ provider = create_provider("cloudflare", settings)
+
+ assert isinstance(provider, CloudflareProvider)
+ assert provider._base_url == (
+ "https://api.cloudflare.com/client/v4/accounts/test-account/ai/v1"
+ )
+
+
def test_opencode_go_provider_config_uses_correct_base_url_and_name():
with patch("httpx.AsyncClient"):
provider = create_provider("opencode_go", _make_settings())
@@ -168,6 +197,8 @@ def test_create_provider_instantiates_each_builtin():
groq_api_key="test_groq_key",
cerebras_api_key="test_cerebras_key",
fireworks_api_key="test_fireworks_key",
+ cloudflare_api_token="test_cloudflare_token",
+ cloudflare_account_id="test_cloudflare_account",
kimi_api_key="test_kimi_key",
)
cases = {
@@ -177,6 +208,7 @@ def test_create_provider_instantiates_each_builtin():
"deepseek": DeepSeekProvider,
"kimi": KimiProvider,
"fireworks": FireworksProvider,
+ "cloudflare": CloudflareProvider,
"lmstudio": LMStudioProvider,
"llamacpp": LlamaCppProvider,
"ollama": OllamaProvider,
diff --git a/uv.lock b/uv.lock
index 048ab67d..834b4f05 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "2.3.23"
+version = "2.4.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },