How to Configure Proxy Settings for the FreeLLMAPI Server

FreeLLMAPI supports HTTP/HTTPS and SOCKS4/5 proxies via the PROXY_URL environment variable or the PUT /api/settings/proxy REST API, with all routing logic centralized in server/src/lib/proxy.ts.

The open-source FreeLLMAPI server (available at tashfeenahmed/freellmapi) routes outbound LLM requests through configurable proxies to meet corporate network requirements. Whether you need to tunnel traffic through an HTTP proxy or route via SOCKS5, the server provides centralized configuration through both startup environment variables and runtime API endpoints.

Understanding the Proxy Architecture

The proxy system relies on two primary components: a core library that manages connection agents and a REST API that exposes configuration controls.

Core Proxy Module

The server/src/lib/proxy.ts file contains the central logic for proxy handling. It exports proxyFetch, which intercepts outbound requests and routes them through the appropriate dispatcher based on current settings. The module maintains internal state through _proxyUrl, _proxyEnabled, and _proxyBypass variables, updated via helper functions applyProxyUrl (lines 40-49), applyProxyEnabled (lines 61-66), and applyProxyBypass (lines 71-78).

Settings API Endpoint

The server/src/routes/settings.ts file exposes the proxy configuration via HTTP endpoints. The GET /api/settings/proxy route returns the current configuration including URL, enabled status, bypass list, and active state. The PUT /api/settings/proxy route accepts partial JSON payloads to update settings at runtime without restarting the server.

Configuration Methods

You can configure the proxy using two methods: environment variables for startup configuration or the REST API for runtime changes.

Environment Variable Setup

Set the PROXY_URL environment variable before starting the server to configure the proxy at startup. This is ideal for Docker deployments or systemd services.

# .env file or shell export

PROXY_URL="socks5://proxy.example:1080"

The server reads this variable during initialization and persists it to the SQLite database via the setSetting function, ensuring the configuration survives restarts.

Runtime API Configuration

Use the PUT /api/settings/proxy endpoint to modify proxy settings without restarting the server. This approach accepts partial updates, meaning you can change individual fields while preserving others.

curl -X PUT http://localhost:3000/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{
    "proxyUrl": "http://proxy.example:3128",
    "enabled": true,
    "bypassPlatforms": ["openai","anthropic"]
  }'

The endpoint validates that the URL uses supported schemes (http:, https:, socks5:, or socks4:) before applying changes.

Proxy Configuration Options

FreeLLMAPI exposes three primary settings to control proxy behavior.

Proxy URL

The proxy URL specifies the full address of your proxy server. The applyProxyUrl function validates and stores this value, logging a masked version for security. Supported formats include http://proxy.example:3128 and socks5://proxy.example:1080.

Enable/Disable Toggle

The enabled boolean allows you to turn proxy routing on or off without clearing the configured URL. The applyProxyEnabled function updates the internal state, while isProxyActive (lines 56-60) checks both that a URL exists and that the proxy is enabled.

curl -X PUT http://localhost:3000/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Bypass Platforms

The bypassPlatforms array defines which LLM providers should bypass the proxy. The applyProxyBypass function processes these values, which proxyFetch checks before routing requests. Specify platforms as an array of identifiers (e.g., ["openai", "anthropic"]).

Validating and Testing Your Configuration

Verify your current proxy state by querying the settings endpoint:

curl http://localhost:3000/api/settings/proxy

A properly configured proxy returns:

{
  "proxyUrl": "http://proxy.example:3128",
  "enabled": true,
  "bypassPlatforms": ["openai"],
  "active": true
}

To remove the proxy entirely, send an empty string for proxyUrl:

curl -X PUT http://localhost:3000/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"proxyUrl": ""}'

Summary

• FreeLLMAPI supports HTTP/HTTPS and SOCKS4/5 proxies via the PROXY_URL environment variable or PUT /api/settings/proxy API calls.
• Core logic resides in server/src/lib/proxy.ts, with API routes defined in server/src/routes/settings.ts.
• Settings persist in SQLite via setSetting/getSetting and survive server restarts.
• Use the enabled flag to toggle proxy status without losing the URL configuration.
• Specify bypassPlatforms as an array of provider identifiers to exclude specific LLM services from proxy routing.

Frequently Asked Questions

What proxy protocols does FreeLLMAPI support?

FreeLLMAPI supports http:, https:, socks5:, and socks4: URL schemes. HTTP and HTTPS traffic routes through undici ProxyAgent instances, while SOCKS connections use HTTP/HTTPS fallbacks. The applyProxyUrl function validates these schemes before accepting configuration.

How do I disable the proxy without losing the URL?

Send a PUT request to /api/settings/proxy with {"enabled": false} or set the environment variable initially and toggle the enabled state via API. The applyProxyEnabled function updates the internal flag while preserving the _proxyUrl value, allowing you to re-enable the proxy instantly.

Can I bypass specific LLM platforms from the proxy?

Yes. Use the bypassPlatforms field to specify an array of platform identifiers (e.g., ["openai", "anthropic"]). The applyProxyBypass function stores these values, and proxyFetch checks each request's target platform against this list before routing through the proxy dispatcher.

Where are proxy settings stored?

Proxy settings persist in the SQLite database via server/src/db/index.ts functions setSetting and getSetting. This ensures that runtime API changes survive server restarts, while the PROXY_URL environment variable provides the initial default value on startup.

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