# How to Configure Proxy Settings for the FreeLLMAPI Server

> Configure proxy settings for FreeLLMAPI server using PROXY_URL or the REST API. Learn how to set up HTTP/HTTPS and SOCKS4/5 proxies easily.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.

```bash

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

```bash
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.

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

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

```

A properly configured proxy returns:

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

```

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

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/proxy.ts)**, with API routes defined in **[`server/src/routes/settings.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.