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

Keep FCC-local traffic off outbound proxies (#1214)

Ali Khokhar258ed3e7ed19
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 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 neutral
proxy-auth token policy shared by client launchers. A blank configured token
becomes the local-only `fcc-no-auth` sentinel so clients cross their login gates
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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_bypass
from free_claude_code.cli.proxy_auth import proxy_auth_token
CLAUDE_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_url
env["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.py
index 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 json
import os
import sys
from 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_token
from free_claude_code.config.paths import codex_model_catalog_path
from 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.py
index 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 subprocess
import sys
from collections.abc import Mapping
from 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_request
from 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.py
index 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 sys
from collections.abc import Mapping, Sequence
from pathlib import Path
+from free_claude_code.cli.local_http import with_local_proxy_bypass
from free_claude_code.cli.proxy_auth import proxy_auth_token
from free_claude_code.config.server_urls import local_proxy_root_url
from 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 env
diff --git a/src/free_claude_code/cli/local_http.py b/src/free_claude_code/cli/local_http.py
new file mode 100644
index 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.py
index 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 env
assert "ANTHROPIC_API_KEY" not in env
assert "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_env
assert 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_env
assert "CODEX_PERMISSION_PROFILE" not in child_env
assert "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.py
new file mode 100644
index 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.py
index 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.env
assert "ANTHROPIC_API_URL" not in invocation.env
assert "ANTHROPIC_API_KEY" not in invocation.env
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index 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.lock
index 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" },