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
Keep FCC-local traffic off outbound proxies (#1214)
Ali Khokhar258ed3e7ed19
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.mdindex 97e4e0d4..83564066 100644--- a/ARCHITECTURE.md+++ b/ARCHITECTURE.md@@ -938,6 +938,14 @@ otherwise the Messages handler rejects them before provider execution.## CLI Launchers And Managed Claude+[cli/local_http.py](src/free_claude_code/cli/local_http.py) owns the direct+agent-to-FCC connection boundary. Launcher health checks and local model-catalog+requests never inherit environment or operating-system forward proxies. Every+spawned agent environment preserves the user's outbound proxy configuration but+adds the configured FCC host and standard loopback names to both `NO_PROXY` and+`no_proxy`. Provider-specific upstream proxies remain provider-owned and do not+participate in this local boundary.+[cli/proxy_auth.py](src/free_claude_code/cli/proxy_auth.py) owns the neutralproxy-auth token policy shared by client launchers. A blank configured tokenbecomes the local-only `fcc-no-auth` sentinel so clients cross their login gatesdiff --git a/pyproject.toml b/pyproject.tomlindex 5f4cad5f..be53a66d 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.11.2"+version = "4.11.3"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/src/free_claude_code/cli/claude_env.py b/src/free_claude_code/cli/claude_env.pyindex 3be8010a..666dbcd2 100644--- a/src/free_claude_code/cli/claude_env.py+++ b/src/free_claude_code/cli/claude_env.py@@ -2,6 +2,7 @@from collections.abc import Mapping+from free_claude_code.cli.local_http import with_local_proxy_bypassfrom free_claude_code.cli.proxy_auth import proxy_auth_tokenCLAUDE_CODE_AUTO_COMPACT_WINDOW = "190000"@@ -17,12 +18,15 @@ def build_claude_proxy_env("""Return the canonical environment for Claude Code proxy sessions."""# Claude's aggregate traffic flag also suppresses gateway model discovery.- env = {- key: value- for key, value in base_env.items()- if not key.startswith("ANTHROPIC_")- and key != "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"- }+ env = with_local_proxy_bypass(+ {+ key: value+ for key, value in base_env.items()+ if not key.startswith("ANTHROPIC_")+ and key != "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"+ },+ proxy_root_url=proxy_root_url,+ )env["ANTHROPIC_BASE_URL"] = proxy_root_urlenv["ANTHROPIC_AUTH_TOKEN"] = proxy_auth_token(auth_token)env["CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY"] = "1"diff --git a/src/free_claude_code/cli/launchers/codex.py b/src/free_claude_code/cli/launchers/codex.pyindex 986b8d43..d911468e 100644--- a/src/free_claude_code/cli/launchers/codex.py+++ b/src/free_claude_code/cli/launchers/codex.py@@ -4,8 +4,12 @@ import jsonimport osimport sysfrom collections.abc import Mapping, Sequence-from urllib.request import Request, urlopen+from urllib.request import Request+from free_claude_code.cli.local_http import (+ open_local_request,+ with_local_proxy_bypass,+)from free_claude_code.cli.proxy_auth import proxy_auth_tokenfrom free_claude_code.config.paths import codex_model_catalog_pathfrom free_claude_code.config.server_urls import local_proxy_root_url@@ -71,6 +75,7 @@ def launch(argv: Sequence[str] | None = None) -> None:catalog_config_args=catalog_args,),env=build_codex_launcher_env(+ proxy_root_url=proxy_root_url,auth_token=settings.anthropic_auth_token,base_env=os.environ,),@@ -109,16 +114,20 @@ def build_codex_launcher_command(def build_codex_launcher_env(*,+ proxy_root_url: str,auth_token: str,base_env: Mapping[str, str],) -> dict[str, str]:"""Return a Codex environment that targets the local proxy provider."""- env = {- key: value- for key, value in base_env.items()- if key not in _STRIPPED_CODEX_ENV_KEYS and not key.startswith("OPENAI_")- }+ env = with_local_proxy_bypass(+ {+ key: value+ for key, value in base_env.items()+ if key not in _STRIPPED_CODEX_ENV_KEYS and not key.startswith("OPENAI_")+ },+ proxy_root_url=proxy_root_url,+ )env[_CODEX_AUTH_ENV_KEY] = proxy_auth_token(auth_token)return env@@ -165,7 +174,9 @@ def fetch_proxy_models_response(headers["Authorization"] = f"Bearer {token}"request = Request(url, headers=headers, method="GET")- with urlopen(request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS) as response:+ with open_local_request(+ request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS+ ) as response:payload = json.loads(response.read().decode("utf-8"))if not isinstance(payload, dict):diff --git a/src/free_claude_code/cli/launchers/common.py b/src/free_claude_code/cli/launchers/common.pyindex a4674cf5..1bea5b17 100644--- a/src/free_claude_code/cli/launchers/common.py+++ b/src/free_claude_code/cli/launchers/common.py@@ -5,8 +5,9 @@ import subprocessimport sysfrom collections.abc import Mappingfrom urllib.error import HTTPError, URLError-from urllib.request import Request, urlopen+from urllib.request import Request+from free_claude_code.cli.local_http import open_local_requestfrom free_claude_code.cli.process_registry import (kill_pid_tree_best_effort,register_pid,@@ -23,7 +24,9 @@ def preflight_proxy(proxy_root_url: str) -> str | None:url = f"{proxy_root_url.rstrip('/')}{PROXY_PREFLIGHT_PATH}"request = Request(url, method="GET")try:- with urlopen(request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS) as response:+ with open_local_request(+ request, timeout=PROXY_PREFLIGHT_TIMEOUT_SECONDS+ ) as response:status_code = response.getcode()except HTTPError as exc:return f"returned HTTP {exc.code}"diff --git a/src/free_claude_code/cli/launchers/pi.py b/src/free_claude_code/cli/launchers/pi.pyindex 59e2553c..a5998a33 100644--- a/src/free_claude_code/cli/launchers/pi.py+++ b/src/free_claude_code/cli/launchers/pi.py@@ -6,6 +6,7 @@ import sysfrom collections.abc import Mapping, Sequencefrom pathlib import Path+from free_claude_code.cli.local_http import with_local_proxy_bypassfrom free_claude_code.cli.proxy_auth import proxy_auth_tokenfrom free_claude_code.config.server_urls import local_proxy_root_urlfrom free_claude_code.config.settings import get_settings@@ -114,9 +115,14 @@ def build_pi_launcher_env() -> dict[str, str]:"""Return a Pi environment containing only FCC-owned proxy variables."""- env = {- key: value for key, value in base_env.items() if not key.startswith("FCC_PI_")- }+ env = with_local_proxy_bypass(+ {+ key: value+ for key, value in base_env.items()+ if not key.startswith("FCC_PI_")+ },+ proxy_root_url=proxy_root_url,+ )env[_BASE_URL_ENV] = proxy_root_url.rstrip("/")env[_API_KEY_ENV] = proxy_auth_token(auth_token)return envdiff --git a/src/free_claude_code/cli/local_http.py b/src/free_claude_code/cli/local_http.pynew file mode 100644index 00000000..01811a88--- /dev/null+++ b/src/free_claude_code/cli/local_http.py@@ -0,0 +1,51 @@+"""Direct HTTP and child-environment policy for FCC-local traffic."""++from collections.abc import Mapping+from typing import Any+from urllib.parse import urlsplit+from urllib.request import ProxyHandler, Request, build_opener++_DIRECT_OPENER = build_opener(ProxyHandler({}))+_LOOPBACK_BYPASS_HOSTS = ("127.0.0.1", "localhost", "::1")+_NO_PROXY_KEYS = ("NO_PROXY", "no_proxy")+++def open_local_request(request: Request, *, timeout: float) -> Any:+ """Open an FCC-local request without consulting machine proxy settings."""++ return _DIRECT_OPENER.open(request, timeout=timeout)+++def with_local_proxy_bypass(+ base_env: Mapping[str, str],+ *,+ proxy_root_url: str,+) -> dict[str, str]:+ """Copy an environment and keep its FCC-local destination off proxies."""++ host = urlsplit(proxy_root_url).hostname+ if host is None:+ raise ValueError("Local proxy root URL must include a host.")++ env = dict(base_env)+ entries: list[str] = []+ seen: set[str] = set()+ for key in _NO_PROXY_KEYS:+ for raw_entry in base_env.get(key, "").split(","):+ _append_unique(entries, seen, raw_entry)+ for local_host in (*_LOOPBACK_BYPASS_HOSTS, host):+ _append_unique(entries, seen, local_host)++ value = ",".join(entries)+ for key in _NO_PROXY_KEYS:+ env[key] = value+ return env+++def _append_unique(entries: list[str], seen: set[str], raw_entry: str) -> None:+ entry = raw_entry.strip()+ normalized = entry.casefold()+ if not entry or normalized in seen:+ return+ entries.append(entry)+ seen.add(normalized)diff --git a/tests/cli/test_entrypoints.py b/tests/cli/test_entrypoints.pyindex e205ab59..c72a8173 100644--- a/tests/cli/test_entrypoints.py+++ b/tests/cli/test_entrypoints.py@@ -503,6 +503,8 @@ def test_claude_child_env_targets_current_proxy_config() -> None:assert env["DISABLE_FEEDBACK_COMMAND"] == "1"assert env["DISABLE_ERROR_REPORTING"] == "1"assert env["DISABLE_TELEMETRY"] == "1"+ assert env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert env["no_proxy"] == env["NO_PROXY"]assert "ANTHROPIC_API_URL" not in envassert "ANTHROPIC_API_KEY" not in envassert "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC" not in env@@ -567,6 +569,8 @@ def test_launch_claude_passes_args_and_child_env(assert child_env["DISABLE_FEEDBACK_COMMAND"] == "1"assert child_env["DISABLE_ERROR_REPORTING"] == "1"assert child_env["DISABLE_TELEMETRY"] == "1"+ assert child_env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert child_env["no_proxy"] == child_env["NO_PROXY"]assert "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC" not in child_envassert child_env["KEEP_ME"] == "yes"register_pid.assert_called_once_with(12345)@@ -627,7 +631,10 @@ def test_launch_codex_passes_responses_config_and_child_env("free_claude_code.cli.launchers.codex.codex_model_catalog_path",return_value=catalog_path,),- patch("free_claude_code.cli.launchers.codex.urlopen", side_effect=fake_urlopen),+ patch(+ "free_claude_code.cli.launchers.codex.open_local_request",+ side_effect=fake_urlopen,+ ),patch("free_claude_code.cli.launchers.common.subprocess.Popen") as popen,patch("free_claude_code.cli.launchers.common.register_pid") as register_pid,patch("free_claude_code.cli.launchers.common.unregister_pid") as unregister_pid,@@ -659,6 +666,8 @@ def test_launch_codex_passes_responses_config_and_child_env(child_env = popen.call_args.kwargs["env"]assert child_env["FCC_CODEX_API_KEY"] == "proxy-token"assert child_env["CODEX_HOME"] == "keep-home"+ assert child_env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert child_env["no_proxy"] == child_env["NO_PROXY"]assert "CODEX_INTERNAL_ORIGINATOR_OVERRIDE" not in child_envassert "CODEX_PERMISSION_PROFILE" not in child_envassert "CODEX_SHELL" not in child_env@@ -693,7 +702,8 @@ def test_launch_codex_catalog_failure_warns_and_continues(return_value=tmp_path / "codex-model-catalog.json",),patch(- "free_claude_code.cli.launchers.codex.urlopen", side_effect=URLError("boom")+ "free_claude_code.cli.launchers.codex.open_local_request",+ side_effect=URLError("boom"),),patch("free_claude_code.cli.launchers.common.subprocess.Popen") as popen,patch("free_claude_code.cli.launchers.common.register_pid"),@@ -749,6 +759,8 @@ def test_pi_launcher_builds_scoped_session_command_and_proxy_env(assert env == {"PATH": "keep","ANTHROPIC_API_KEY": "native-pi-credential",+ "NO_PROXY": "127.0.0.1,localhost,::1",+ "no_proxy": "127.0.0.1,localhost,::1","FCC_PI_BASE_URL": "http://127.0.0.1:9191","FCC_PI_API_KEY": "proxy-token",}@@ -816,6 +828,8 @@ def test_launch_pi_registers_bundled_extension_for_sessions(child_env = popen.call_args.kwargs["env"]assert child_env["FCC_PI_BASE_URL"] == "http://127.0.0.1:9191"assert child_env["FCC_PI_API_KEY"] == "proxy-token"+ assert child_env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert child_env["no_proxy"] == child_env["NO_PROXY"]assert child_env["KEEP_ME"] == "yes"diff --git a/tests/cli/test_local_http.py b/tests/cli/test_local_http.pynew file mode 100644index 00000000..58a3d76a--- /dev/null+++ b/tests/cli/test_local_http.py@@ -0,0 +1,84 @@+"""Local FCC transport must never escape through an outbound proxy."""++import threading+from collections.abc import Iterator+from contextlib import contextmanager+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer++import pytest++from free_claude_code.cli.launchers.common import preflight_proxy+from free_claude_code.cli.local_http import with_local_proxy_bypass+++@contextmanager+def _status_server(status_code: int) -> Iterator[tuple[str, list[str]]]:+ hits: list[str] = []++ class Handler(BaseHTTPRequestHandler):+ def do_GET(self) -> None:+ hits.append(self.path)+ self.send_response(status_code)+ self.end_headers()++ def log_message(self, format: str, *args: object) -> None:+ del format, args++ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ thread = threading.Thread(target=server.serve_forever, daemon=True)+ thread.start()+ try:+ yield f"http://127.0.0.1:{server.server_port}", hits+ finally:+ server.shutdown()+ server.server_close()+ thread.join()+++def test_proxy_preflight_connects_directly_when_http_proxy_is_configured(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ with _status_server(502) as (forward_proxy_url, forward_proxy_hits):+ monkeypatch.setenv("HTTP_PROXY", forward_proxy_url)+ monkeypatch.setenv("http_proxy", forward_proxy_url)+ monkeypatch.delenv("NO_PROXY", raising=False)+ monkeypatch.delenv("no_proxy", raising=False)++ with _status_server(200) as (fcc_url, fcc_hits):+ assert preflight_proxy(fcc_url) is None++ assert fcc_hits == ["/health"]+ assert forward_proxy_hits == []+++def test_child_proxy_bypass_preserves_existing_proxy_policy() -> None:+ base_env = {+ "HTTP_PROXY": "http://proxy.example:3128",+ "NO_PROXY": "example.com, localhost",+ "no_proxy": "10.0.0.0/8,EXAMPLE.COM",+ "KEEP_ME": "yes",+ }++ env = with_local_proxy_bypass(+ base_env,+ proxy_root_url="http://fcc.internal:8082",+ )++ assert env["HTTP_PROXY"] == "http://proxy.example:3128"+ assert env["KEEP_ME"] == "yes"+ assert env["NO_PROXY"] == (+ "example.com,localhost,10.0.0.0/8,127.0.0.1,::1,fcc.internal"+ )+ assert env["no_proxy"] == env["NO_PROXY"]+ assert base_env["NO_PROXY"] == "example.com, localhost"+ assert base_env["no_proxy"] == "10.0.0.0/8,EXAMPLE.COM"+++def test_child_proxy_bypass_uses_all_loopback_spellings_without_duplicates() -> None:+ env = with_local_proxy_bypass(+ {"NO_PROXY": "127.0.0.1"},+ proxy_root_url="http://127.0.0.1:8082",+ )++ assert env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert env["no_proxy"] == env["NO_PROXY"]diff --git a/tests/cli/test_managed_claude.py b/tests/cli/test_managed_claude.pyindex 7aa0fd1a..a1e1819a 100644--- a/tests/cli/test_managed_claude.py+++ b/tests/cli/test_managed_claude.py@@ -72,6 +72,8 @@ def test_managed_claude_builds_new_task_command_and_env() -> None:assert invocation.env["DISABLE_FEEDBACK_COMMAND"] == "1"assert invocation.env["DISABLE_ERROR_REPORTING"] == "1"assert invocation.env["DISABLE_TELEMETRY"] == "1"+ assert invocation.env["NO_PROXY"] == "127.0.0.1,localhost,::1"+ assert invocation.env["no_proxy"] == invocation.env["NO_PROXY"]assert "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC" not in invocation.envassert "ANTHROPIC_API_URL" not in invocation.envassert "ANTHROPIC_API_KEY" not in invocation.envdiff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.pyindex f192c5c4..dfaad318 100644--- a/tests/contracts/test_import_boundaries.py+++ b/tests/contracts/test_import_boundaries.py@@ -226,6 +226,31 @@ def test_google_reasoning_wire_fields_have_one_owner() -> None:assert sorted(offenders) == []+def test_cli_local_http_transport_has_one_owner() -> None:+ cli_root = _PACKAGE_ROOT / "cli"+ owner = cli_root / "local_http.py"+ owned_urllib_names = {"ProxyHandler", "build_opener", "urlopen"}+ owned_environment_keys = {"NO_PROXY", "no_proxy"}+ offenders: list[str] = []++ for path in cli_root.rglob("*.py"):+ if path == owner:+ continue+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))+ relative_path = path.relative_to(_REPO_ROOT).as_posix()+ for node in ast.walk(tree):+ if isinstance(node, ast.ImportFrom) and node.module == "urllib.request":+ offenders.extend(+ f"{relative_path}:{node.lineno}: urllib.request.{alias.name}"+ for alias in node.names+ if alias.name in owned_urllib_names+ )+ if isinstance(node, ast.Constant) and node.value in owned_environment_keys:+ offenders.append(f"{relative_path}:{node.lineno}: {node.value}")++ assert sorted(offenders) == []++def test_provider_backchannel_detector_reports_untyped_private_access(tmp_path: Path,) -> None:diff --git a/uv.lock b/uv.lockindex 681da6bf..62ee825b 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.11.2"+version = "4.11.3"source = { editable = "." }dependencies = [{ name = "aiohttp" },