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
Feature/poolside support (#1483)
Parsa.py20b7e45f88c4
diff --git a/.env.example b/.env.exampleindex afdaf61f..d908ca4f 100644--- a/.env.example+++ b/.env.example@@ -78,6 +78,10 @@ TOKENROUTER_BASE_URL="https://api.tokenrouter.com/v1"# NARAROUTE_API_KEY=<your-token>NARAROUTE_BASE_URL="https://router.bynara.id/v1"++# Poolside AI (OpenAI-compatible Chat Completions at inference.poolside.ai/v1)+# POOLSIDE_API_KEY=<your-token>+# Fireworks AI Config (OpenAI-compatible Chat Completions at api.fireworks.ai/inference/v1)# FIREWORKS_API_KEY=<your-token>@@ -187,7 +191,7 @@ OLLAMA_BASE_URL="http://localhost:11434"# Default model and optional Claude tier overrides# Format: provider_type/model/name-# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "cline_pass" | "xai" | "qwencloud" | "qwencloud_coding" | "together" | "deepinfra" | "siliconflow" | "nebius" | "chutes" | "featherless" | "agnes" | "zenmux" | "wandb" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"+# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "cline_pass" | "xai" | "qwencloud" | "qwencloud_coding" | "together" | "deepinfra" | "siliconflow" | "nebius" | "chutes" | "featherless" | "agnes" | "zenmux" | "wandb" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute" | "poolside"# MODEL_FABLE=<provider/model-id># MODEL_OPUS=<provider/model-id># MODEL_SONNET=<provider/model-id>@@ -227,6 +231,7 @@ MODEL="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"# FCC_SMOKE_MODEL_ZAI_API=<provider/model-id># FCC_SMOKE_MODEL_TOKENROUTER=<your-token># FCC_SMOKE_MODEL_NARAROUTE=<provider/model-id>+# FCC_SMOKE_MODEL_POOLSIDE=<provider/model-id># FCC_SMOKE_MODEL_FIREWORKS=<provider/model-id># FCC_SMOKE_MODEL_NOVITA=<provider/model-id># FCC_SMOKE_MODEL_CLOUDFLARE=<provider/model-id>@@ -302,6 +307,7 @@ REASONING_HAIKU=inherit# ZAI_API_PROXY=<http-or-socks-url># TOKENROUTER_PROXY=<http-or-socks-url># NARAROUTE_PROXY=<http-or-socks-url>+# POOLSIDE_PROXY=<http-or-socks-url># FIREWORKS_PROXY=<http-or-socks-url># NOVITA_PROXY=<http-or-socks-url># CLOUDFLARE_PROXY=<http-or-socks-url>diff --git a/README.md b/README.mdindex 279b2e1e..e5614151 100644--- a/README.md+++ b/README.md@@ -25,7 +25,7 @@## What You Get-- **48 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.+- **49 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. FCC follows provider terms and removes integrations if they stop being allowed.- **9 coding agents. One model catalog.** Run [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), [Hermes](https://github.com/NousResearch/hermes-agent), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [Grok Build](https://github.com/xai-org/grok-build), or [Muse Code](https://research.meta.ai/blog/introducing-muse-code-and-muse-spark-1-2/) with your FCC models.- **Keep coding through provider outages.** After retries are exhausted, FCC automatically tries your next configured model without making you restart the turn—across every client.- **Up to 90% fewer terminal-output tokens.** Optional [RTK](https://github.com/rtk-ai/rtk) filters common command output, while five FCC optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.@@ -249,6 +249,7 @@ from more than one provider before succeeding.| [Z.ai API (pay as you go)](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai_api/glm-4.7-flash` || [TokenRouter](https://www.tokenrouter.com/) | `TOKENROUTER_API_KEY` | `tokenrouter/moonshotai/kimi-k3-free` || [NaraRoute](https://router.bynara.id/) | `NARAROUTE_API_KEY` | `nararoute/kimi-k3-free` |+| [Poolside AI](https://platform.poolside.ai/) | `POOLSIDE_API_KEY` | `poolside/poolside/laguna-s-2.1` || [Ollama Cloud](https://ollama.com/settings/keys) | `OLLAMA_API_KEY` | `ollama_cloud/qwen3-coder:480b` || [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/<model-id>` || [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/<model-id>` |diff --git a/pyproject.toml b/pyproject.tomlindex f850d0a5..7fb27a74 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "5.12.2"+version = "5.13.0"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/smoke/lib/config.py b/smoke/lib/config.pyindex ea4eeaa5..87675620 100644--- a/smoke/lib/config.py+++ b/smoke/lib/config.py@@ -89,6 +89,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {"cloudflare": "cloudflare/@cf/moonshotai/kimi-k2.6","tokenrouter": "tokenrouter/moonshotai/kimi-k3-free","nararoute": "nararoute/kimi-k3-free",+ "poolside": "poolside/poolside/laguna-s-2.1","agnes": "agnes/agnes-2.0-flash","zenmux": "zenmux/deepseek/deepseek-v4-flash-free","wandb": "wandb/openai/gpt-oss-20b",diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.pyindex 4d27354b..bbf3c2a3 100644--- a/src/free_claude_code/config/provider_catalog.py+++ b/src/free_claude_code/config/provider_catalog.py@@ -77,6 +77,8 @@ FEATHERLESS_DEFAULT_BASE = "https://api.featherless.ai/v1"TOKENROUTER_DEFAULT_BASE = "https://api.tokenrouter.com/v1"# NaraRoute OpenAI-compatible Chat Completions gateway.NARAROUTE_DEFAULT_BASE = "https://router.bynara.id/v1"+# Poolside AI OpenAI-compatible Chat Completions API.+POOLSIDE_DEFAULT_BASE = "https://inference.poolside.ai/v1"# Agnes AI OpenAI-compatible Chat Completions API.AGNES_DEFAULT_BASE = "https://apihub.agnes-ai.com/v1"# ZenMux OpenAI-compatible Chat Completions gateway.@@ -527,6 +529,15 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {base_url_attr="nararoute_base_url",proxy_attr="nararoute_proxy",),+ "poolside": ProviderDescriptor(+ provider_id="poolside",+ display_name="Poolside AI",+ credential_env="POOLSIDE_API_KEY",+ credential_url="https://platform.poolside.ai/",+ credential_attr="poolside_api_key",+ default_base_url=POOLSIDE_DEFAULT_BASE,+ proxy_attr="poolside_proxy",+ ),"ollama_cloud": ProviderDescriptor(provider_id="ollama_cloud",display_name="Ollama Cloud",diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.pyindex 7f2f814c..d0b605fb 100644--- a/src/free_claude_code/config/settings.py+++ b/src/free_claude_code/config/settings.py@@ -196,6 +196,11 @@ class Settings(BaseModel):validation_alias="NARAROUTE_BASE_URL",)+ # ==================== Poolside AI (OpenAI-compatible) ====================+ poolside_api_key: OptionalNonEmptyString = Field(+ default=None, validation_alias="POOLSIDE_API_KEY"+ )+# ==================== Fireworks AI Config ====================fireworks_api_key: OptionalNonEmptyString = Field(default=None, validation_alias="FIREWORKS_API_KEY"@@ -482,6 +487,9 @@ class Settings(BaseModel):nararoute_proxy: OptionalNonEmptyString = Field(default=None, validation_alias="NARAROUTE_PROXY")+ poolside_proxy: OptionalNonEmptyString = Field(+ default=None, validation_alias="POOLSIDE_PROXY"+ )fireworks_proxy: OptionalNonEmptyString = Field(default=None, validation_alias="FIREWORKS_PROXY")@@ -509,7 +517,6 @@ class Settings(BaseModel):ollama_cloud_proxy: OptionalNonEmptyString = Field(default=None, validation_alias="OLLAMA_CLOUD_PROXY")-# ==================== Provider Rate Limiting ====================provider_rate_limit: int = Field(default=1, validation_alias="PROVIDER_RATE_LIMIT")provider_rate_window: int = Field(diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.pyindex 6dac8048..eaa8807e 100644--- a/src/free_claude_code/providers/openai_chat/profiles.py+++ b/src/free_claude_code/providers/openai_chat/profiles.py@@ -613,6 +613,16 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {enabled_value="medium",),),+ "poolside": OpenAIChatProfile(+ _policy(+ "POOLSIDE",+ ReasoningReplayMode.REASONING_CONTENT,+ include_extra_body=True,+ extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,+ ),+ ChatTemplateReasoning(field="enable_thinking"),+ ),"ollama_cloud": OpenAIChatProfile(_policy("OLLAMA_CLOUD",diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.pyindex 50921604..3f214576 100644--- a/tests/contracts/test_provider_catalog_order.py+++ b/tests/contracts/test_provider_catalog_order.py@@ -50,6 +50,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = ("zai_api","tokenrouter","nararoute",+ "poolside","ollama_cloud","lmstudio","llamacpp",diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.pyindex 7a455cda..d18003d1 100644--- a/tests/contracts/test_smoke_config.py+++ b/tests/contracts/test_smoke_config.py@@ -67,6 +67,7 @@ def _settings(**overrides):"sambanova_api_key": "","cerebras_api_key": "","ollama_api_key": "",+ "poolside_api_key": "","fireworks_api_key": "","novita_api_key": "","cloudflare_api_token": "",@@ -162,6 +163,25 @@ def test_provider_smoke_models_cover_configured_providers_independent_of_model_massert models[0].source == "provider_default"+def test_poolside_provider_configuration_uses_documented_default_model(+ monkeypatch,+) -> None:+ monkeypatch.delenv("FCC_SMOKE_MODEL_POOLSIDE", raising=False)+ config = _smoke_config(+ settings=_settings(+ model="ollama/llama3.1",+ ollama_base_url="",+ poolside_api_key="poolside-key",+ )+ )++ assert config.has_provider_configuration("poolside")+ models = config.provider_smoke_models()+ assert [model.provider for model in models] == ["poolside"]+ assert models[0].full_model == "poolside/poolside/laguna-s-2.1"+ assert models[0].source == "provider_default"++def test_xai_provider_smoke_uses_current_grok_model(monkeypatch) -> None:monkeypatch.delenv("FCC_SMOKE_MODEL_XAI", raising=False)config = _smoke_config(diff --git a/tests/providers/test_poolside.py b/tests/providers/test_poolside.pynew file mode 100644index 00000000..4c81fa4c--- /dev/null+++ b/tests/providers/test_poolside.py@@ -0,0 +1,217 @@+"""Tests for the Poolside AI OpenAI-chat provider profile."""++from types import SimpleNamespace++import httpx2+import pytest+from openai import AsyncOpenAI++from free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfo+from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS+from free_claude_code.config.provider_catalog import POOLSIDE_DEFAULT_BASE+from free_claude_code.core.anthropic.models import MessagesRequest+from free_claude_code.core.json_types import JsonObject, JsonValue+from free_claude_code.core.reasoning import ReasoningPolicy+from free_claude_code.providers.openai_chat import OpenAIChatProvider+from tests.providers.support import (+ REASONING_OFF,+ REASONING_ON,+ capture_openai_chat_wire_body,+ immediate_admission,+ make_provider_config,+ profiled_provider,+ reasoning_for,+)++_MODEL = "poolside/laguna-s-2.1"+++def poolside_provider() -> OpenAIChatProvider:+ return profiled_provider(+ "poolside",+ make_provider_config(+ api_key="test-poolside-key",+ base_url=POOLSIDE_DEFAULT_BASE,+ rate_limit=10,+ rate_window=60,+ ),+ admission=immediate_admission(provider_name="poolside", max_attempts=1),+ )+++def _request(**overrides: JsonValue) -> MessagesRequest:+ payload: JsonObject = {+ "model": _MODEL,+ "messages": [{"role": "user", "content": "Hello"}],+ }+ payload.update(overrides)+ return MessagesRequest.model_validate(payload)+++ ("reasoning", "enabled"),+ [(REASONING_OFF, False), (REASONING_ON, True)],+)+def test_encodes_documented_chat_template_thinking_control(+ poolside_provider: OpenAIChatProvider,+ reasoning: ReasoningPolicy,+ enabled: bool,+) -> None:+ body = poolside_provider._build_request_body(+ _request(extra_body={"top_k": 20}),+ reasoning=reasoning,+ )++ assert body["max_tokens"] == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS+ assert body["extra_body"] == {+ "top_k": 20,+ "chat_template_kwargs": {"enable_thinking": enabled},+ }+++def test_omits_thinking_control_for_poolside_default(+ poolside_provider: OpenAIChatProvider,+) -> None:+ body = poolside_provider._build_request_body(+ _request(),+ reasoning=ReasoningPolicy.provider_default(),+ )++ assert "extra_body" not in body+++ "field",+ ["reasoning", "reasoning_effort", "thinking", "enable_thinking"],+)+def test_rejects_caller_reasoning_override(+ poolside_provider: OpenAIChatProvider,+ field: str,+) -> None:+ request = _request(extra_body={field: "caller-owned"})++ with pytest.raises(InvalidRequestError, match="must not override reasoning"):+ poolside_provider._build_request_body(request, reasoning=REASONING_ON)+++def test_replays_reasoning_content_with_tool_history(+ poolside_provider: OpenAIChatProvider,+) -> None:+ request = _request(+ messages=[+ {"role": "user", "content": "Inspect the file."},+ {+ "role": "assistant",+ "content": [+ {"type": "thinking", "thinking": "Read it first."},+ {"type": "text", "text": "I will inspect it."},+ {+ "type": "tool_use",+ "id": "toolu_1",+ "name": "read_file",+ "input": {"path": "example.py"},+ },+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "toolu_1",+ "content": "print('hello')",+ }+ ],+ },+ ]+ )++ body = poolside_provider._build_request_body(+ request,+ reasoning=reasoning_for(request),+ )++ assert body["messages"][1] == {+ "role": "assistant",+ "content": "I will inspect it.",+ "reasoning_content": "Read it first.",+ "tool_calls": [+ {+ "id": "toolu_1",+ "type": "function",+ "function": {+ "name": "read_file",+ "arguments": '{"path": "example.py"}',+ },+ }+ ],+ }+ assert body["messages"][2] == {+ "role": "tool",+ "tool_call_id": "toolu_1",+ "content": "print('hello')",+ }+ assert (+ poolside_provider._profile.reasoning_delta(+ SimpleNamespace(reasoning_content="next thought")+ )+ == "next thought"+ )+++async def test_thinking_control_reaches_wire_as_top_level_extension(+ poolside_provider: OpenAIChatProvider,+) -> None:+ body = poolside_provider._build_request_body(+ _request(),+ reasoning=REASONING_OFF,+ )++ wire = await capture_openai_chat_wire_body(body)++ assert wire["chat_template_kwargs"] == {"enable_thinking": False}+ assert "extra_body" not in wire+++async def test_model_catalog_uses_documented_url_and_bearer_auth(+ poolside_provider: OpenAIChatProvider,+) -> None:+ requests: list[httpx2.Request] = []++ def handler(request: httpx2.Request) -> httpx2.Response:+ requests.append(request)+ return httpx2.Response(+ 200,+ json={+ "object": "list",+ "data": [+ {+ "id": _MODEL,+ "object": "model",+ "created": 0,+ "owned_by": "poolside",+ }+ ],+ },+ )++ await poolside_provider._client.close()+ poolside_provider._client = AsyncOpenAI(+ api_key="wire-poolside-key",+ base_url=POOLSIDE_DEFAULT_BASE,+ max_retries=0,+ http_client=httpx2.AsyncClient(transport=httpx2.MockTransport(handler)),+ )+ try:+ model_infos = await poolside_provider.list_model_infos()+ finally:+ await poolside_provider.cleanup()++ assert model_infos == frozenset({ProviderModelInfo(_MODEL)})+ assert len(requests) == 1+ assert str(requests[0].url) == "https://inference.poolside.ai/v1/models"+ assert requests[0].headers["authorization"] == "Bearer wire-poolside-key"diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.pyindex 63e278f2..2062dd0e 100644--- a/tests/providers/test_provider_runtime.py+++ b/tests/providers/test_provider_runtime.py@@ -25,6 +25,7 @@ from free_claude_code.config.provider_catalog import (NARAROUTE_DEFAULT_BASE,NEBIUS_DEFAULT_BASE,OLLAMA_CLOUD_DEFAULT_BASE,+ POOLSIDE_DEFAULT_BASE,PROVIDER_CATALOG,QWENCLOUD_CODING_DEFAULT_BASE,QWENCLOUD_DEFAULT_BASE,@@ -107,6 +108,7 @@ def _make_settings(**overrides):mock.llamacpp_base_url = "http://localhost:8080/v1"mock.ollama_base_url = "http://localhost:11434"mock.ollama_api_key = "test_ollama_cloud_key"+ mock.poolside_api_key = "test_poolside_key"mock.nvidia_nim_proxy = Nonemock.open_router_proxy = Nonemock.lmstudio_proxy = None@@ -152,6 +154,7 @@ def _make_settings(**overrides):mock.cerebras_api_key = ""mock.cerebras_proxy = Nonemock.ollama_cloud_proxy = None+ mock.poolside_proxy = Nonemock.kilo_api_key = "test_kilo_key"mock.kilo_proxy = Nonemock.openai_proxy = None@@ -233,6 +236,30 @@ def test_ollama_cloud_provider_config_uses_key_and_proxy():assert config.proxy == "http://proxy.test:8080"+def test_poolside_provider_config_uses_key_base_and_proxy() -> None:+ descriptor = PROVIDER_CATALOG["poolside"]+ settings = _make_settings(+ poolside_api_key="poolside-token",+ poolside_proxy="http://proxy.test:8080",+ )++ config = build_provider_config(descriptor, settings)+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):+ provider = create_provider("poolside", settings)++ assert descriptor.display_name == "Poolside AI"+ assert descriptor.credential_env == "POOLSIDE_API_KEY"+ assert descriptor.credential_attr == "poolside_api_key"+ assert descriptor.credential_url == "https://platform.poolside.ai/"+ assert descriptor.default_base_url == POOLSIDE_DEFAULT_BASE+ assert descriptor.base_url_attr is None+ assert descriptor.proxy_attr == "poolside_proxy"+ assert config.api_key == "poolside-token"+ assert config.base_url == POOLSIDE_DEFAULT_BASE+ assert config.proxy == "http://proxy.test:8080"+ assert isinstance(provider, OpenAIChatProvider)++def test_xai_provider_config_uses_key_base_and_proxy() -> None:descriptor = PROVIDER_CATALOG["xai"]settings = _make_settings(@@ -843,6 +870,7 @@ def test_create_provider_instantiates_each_builtin():"ollama_cloud": OpenAIChatProvider,"wafer": OpenAIChatProvider,"opencode_zen": OpenAIChatProvider,+ "poolside": OpenAIChatProvider,"opencode_go": OpenAIChatProvider,"vercel": OpenAIChatProvider,"bedrock": OpenAIChatProvider,diff --git a/uv.lock b/uv.lockindex 72df5aa8..eefb9276 100644--- a/uv.lock+++ b/uv.lock@@ -607,7 +607,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "5.12.2"+version = "5.13.0"source = { editable = "." }dependencies = [{ name = "aiohttp" },