How to Configure Provider-Specific Proxy Settings for free-claude-code

Set the environment variables NVIDIA_NIM_PROXY, OPENROUTER_PROXY, LMSTUDIO_PROXY, or LLAMACPP_PROXY to route specific LLM provider traffic through dedicated HTTP proxies, with the Alishahryar1/free-claude-code project automatically injecting these into the respective provider clients.

The free-claude-code repository supports routing requests for different LLM providers through separate proxy servers. Unlike global proxy settings, this architecture allows you to send NVIDIA NIM traffic through one proxy while routing OpenRouter requests through another, configured centrally in config/settings.py and injected via FastAPI dependencies.

Understanding the Proxy Configuration Architecture

The proxy system operates across three layers: centralized settings, dependency injection, and HTTP client initialization. Each supported provider has a dedicated configuration field that maps directly to environment variables.

Configuration Layer in settings.py

All provider-specific proxy settings reside in config/settings.py. Each supported LLM backend has a distinct string field:

• nvidia_nim_proxy – maps to NVIDIA_NIM_PROXY
• open_router_proxy – maps to OPENROUTER_PROXY
• lmstudio_proxy – maps to LMSTUDIO_PROXY
• llamacpp_proxy – maps to LLAMACPP_PROXY

These fields are defined at lines 30-34 of config/settings.py and accept standard proxy URLs (HTTP, HTTPS, or SOCKS5).

Dependency Injection in dependencies.py

When the FastAPI application builds provider instances, api/dependencies.py handles proxy extraction and injection:

1. Validation: The _get_proxy_value function (lines 26-30) validates that the proxy is a non-empty string, filtering out None values and empty strings.
2. Configuration Building: The _create_provider_for_type function (lines 33-40) constructs a ProviderConfig object, assigning the validated proxy to the proxy attribute before passing it to the provider constructor.

HTTP Client Initialization

OpenAI-compatible providers inherit from providers/openai_compat.py, where the proxy is applied to an httpx.AsyncClient at lines 48-51. The underlying AsyncOpenAI client reuses this configured HTTP client for all subsequent requests.

Setting Up Provider-Specific Proxies

Configure proxies via environment variables or a .env file in the project root or $HOME/.config/free-claude-code/.env.

Environment Variable Configuration

Create or edit your .env file with provider-specific proxy URLs:

# NVIDIA NIM provider

NVIDIA_NIM_PROXY="http://proxy.example:8080"

# OpenRouter provider

OPENROUTER_PROXY="http://router-proxy.local:3128"

# LM Studio provider

LMSTUDIO_PROXY="socks5://sock-proxy:1080"

# Llama.cpp provider - empty string disables proxy

LLAMACPP_PROXY=""

Verifying Configuration

Validate that settings load correctly using the settings getter:

from config.settings import get_settings

settings = get_settings()
print("NVIDIA NIM proxy:", settings.nvidia_nim_proxy)
print("OpenRouter proxy:", settings.open_router_proxy)
print("LM Studio proxy:", settings.lmstudio_proxy)
print("Llama.cpp proxy:", settings.llamacpp_proxy)

Manual Provider Configuration (Advanced)

For custom implementations outside the FastAPI dependency injection system, manually construct ProviderConfig objects with explicit proxy values:

from config.settings import get_settings
from providers.base import ProviderConfig
from providers.nvidia_nim import NvidiaNimProvider
from providers.open_router import OpenRouterProvider

settings = get_settings()

# Configure NVIDIA NIM with dedicated proxy

nim_config = ProviderConfig(
    api_key=settings.nvidia_nim_api_key,
    base_url="https://api.nvidia.com/v1",
    rate_limit=settings.provider_rate_limit,
    rate_window=settings.provider_rate_window,
    max_concurrency=settings.provider_max_concurrency,
    http_read_timeout=settings.http_read_timeout,
    http_write_timeout=settings.http_write_timeout,
    http_connect_timeout=settings.http_connect_timeout,
    enable_thinking=settings.enable_thinking,
    proxy=settings.nvidia_nim_proxy,  # Explicit proxy injection

)

nim_provider = NvidiaNimProvider(nim_config)

# Configure OpenRouter with separate proxy

router_config = ProviderConfig(
    api_key=settings.open_router_api_key,
    base_url="https://openrouter.ai/api/v1",
    rate_limit=settings.provider_rate_limit,
    rate_window=settings.provider_rate_window,
    max_concurrency=settings.provider_max_concurrency,
    http_read_timeout=settings.http_read_timeout,
    http_write_timeout=settings.http_write_timeout,
    http_connect_timeout=settings.http_connect_timeout,
    enable_thinking=settings.enable_thinking,
    proxy=settings.open_router_proxy,  # Distinct proxy for OpenRouter

)

router_provider = OpenRouterProvider(router_config)

Proxy Configuration Flow

The complete data flow from environment variable to HTTP request follows this path:

1. Environment: Variables set in shell or .env file
2. Settings: config/settings.py loads values into provider-specific fields (lines 30-34)
3. Validation: api/dependencies.py _get_proxy_value filters valid strings (lines 26-30)
4. Injection: api/dependencies.py _create_provider_for_type builds ProviderConfig with proxy (lines 33-40)
5. Client Creation: providers/openai_compat.py initializes httpx.AsyncClient(proxy=...) (lines 48-51)

This architecture ensures each provider maintains isolated proxy settings while sharing common rate limiting and timeout configurations.

Summary

• Provider-specific proxies in free-claude-code use dedicated environment variables: NVIDIA_NIM_PROXY, OPENROUTER_PROXY, LMSTUDIO_PROXY, and LLAMACPP_PROXY
• Configuration storage resides in config/settings.py with automatic environment variable mapping
• Validation logic in api/dependencies.py ignores empty strings and non-string values via _get_proxy_value
• HTTP client setup occurs in providers/openai_compat.py, where validated proxies configure httpx.AsyncClient instances
• Multiple proxy types are supported including HTTP, HTTPS, and SOCKS5 URLs

Frequently Asked Questions

What environment variables does free-claude-code use for proxies?

free-claude-code recognizes four provider-specific proxy environment variables: NVIDIA_NIM_PROXY for NVIDIA NIM endpoints, OPENROUTER_PROXY for OpenRouter requests, LMSTUDIO_PROXY for LM Studio connections, and LLAMACPP_PROXY for Llama.cpp servers. These map directly to settings defined in config/settings.py at lines 30-34.

How does free-claude-code validate proxy settings?

The _get_proxy_value function in api/dependencies.py (lines 26-30) validates proxy settings by checking that the value is an instance of str and is non-empty. This prevents None values or empty strings from being passed to the HTTP client, ensuring only valid proxy URLs reach the httpx.AsyncClient configuration.

Can I use different proxy types with free-claude-code?

Yes, the proxy configuration accepts any URL format supported by httpx, including HTTP (http://), HTTPS (https://), and SOCKS5 (socks5://) proxies. The value is passed directly to the httpx.AsyncClient constructor in providers/openai_compat.py without modification, allowing standard Python HTTP client proxy protocols.

Where is the proxy configuration injected in the request lifecycle?

Proxy injection occurs during provider instantiation in the FastAPI dependency layer. The _create_provider_for_type function in api/dependencies.py (lines 33-40) creates a ProviderConfig object containing the proxy value, which is then passed to the provider constructor. The base OpenAI-compatible provider class uses this configuration when initializing its internal httpx.AsyncClient at lines 48-51 of providers/openai_compat.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}