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

> Learn how to configure provider-specific proxy settings for free-claude-code using environment variables like NVIDIA NIM PROXY OPENROUTER PROXY and more. Route traffic effectively.

- Repository: [Ali Khokhar/free-claude-code](https://github.com/Alishahryar1/free-claude-code)
- Tags: how-to-guide
- Published: 2026-04-24

---

**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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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:

```dotenv

# 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:

```python
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:

```python
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`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) loads values into provider-specific fields (lines 30-34)
3. **Validation**: [`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/dependencies.py) `_get_proxy_value` filters valid strings (lines 26-30)
4. **Injection**: [`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/dependencies.py) `_create_provider_for_type` builds `ProviderConfig` with proxy (lines 33-40)
5. **Client Creation**: [`providers/openai_compat.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) with automatic environment variable mapping
- **Validation logic** in [`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/api/dependencies.py) ignores empty strings and non-string values via `_get_proxy_value`
- **HTTP client setup** occurs in [`providers/openai_compat.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/config/settings.py) at lines 30-34.

### How does free-claude-code validate proxy settings?

The `_get_proxy_value` function in [`api/dependencies.py`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/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`](https://github.com/Alishahryar1/free-claude-code/blob/main/providers/openai_compat.py).