# How to Configure a Proxy URL for FreeLLMAPI Docker Deployment

> Easily configure a proxy URL for FreeLLMAPI Docker deployment. Set PROXY_URL and extra_hosts in Docker Compose to route LLM requests through a host-side proxy.

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

---

**Set the `PROXY_URL` environment variable to `socks5h://host.docker.internal:PORT` in your Docker Compose file and add the `extra_hosts` mapping to route all outbound LLM requests through a host-side proxy.**

FreeLLMAPI is an open-source unified API gateway that aggregates multiple large language model providers. When deploying the service via Docker, network isolation prevents the container from reaching proxies running on the host loopback interface. This guide explains how to configure outbound proxy support using the environment variable hierarchy defined in the [tashfeenahmed/freellmapi](https://github.com/tashfeenahmed/freellmapi) source code.

## Understanding the Proxy Precedence Hierarchy

According to [[`docs/env/03-outbound-proxies.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md), FreeLLMAPI evaluates proxy settings in the following strict precedence order:

1. **`PROXY_URL`** – Environment variable with the highest priority
2. **Dashboard UI** – Settings under Keys → Outbound proxy
3. **`ALL_PROXY`** – Standard catch-all variable
4. **`HTTPS_PROXY`** / **`HTTP_PROXY`** – Standard uppercase or lowercase variants
5. **`NO_PROXY`** – Comma-separated list of hosts to bypass (evaluated last)

For Docker deployments, the `PROXY_URL` environment variable is the recommended configuration method because it overrides all other settings and persists across container restarts.

## The Docker Networking Constraint

A critical architecture detail documented in [[`docs/install.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.md) and [[`docs/deployment/01-docker.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/deployment/01-docker.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/deployment/01-docker.md) is that `127.0.0.1` or `localhost` inside a Docker container refers to the container itself, not the Docker host. If your proxy client runs on the host machine (e.g., Clash, v2rayN, or Sing-Box), referencing `127.0.0.1` from within the container will fail silently.

The solution is to use the special DNS name `host.docker.internal`, which resolves to the host gateway. On Linux systems, this hostname requires explicit mapping through Docker Compose `extra_hosts` or the `--add-host` runtime flag.

## Step-by-Step Docker Compose Configuration

### Select the Appropriate Proxy Scheme

FreeLLMAPI supports multiple proxy schemes as defined in the configuration layer:

- **`http://`** or **`https://`** for standard HTTP proxies
- **`socks4://`** or **`socks4a://`** for SOCKS4 (use `socks4a` for remote DNS resolution)
- **`socks5://`** or **`socks5h://`** for SOCKS5 (use `socks5h` to force DNS resolution at the proxy)

For networks with DNS poisoning or restrictive firewalls, **`socks5h`** is recommended to ensure domain names resolve through the proxy rather than locally.

### Map the Host Gateway

Add the `extra_hosts` directive to your [`docker-compose.yml`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml) to enable `host.docker.internal` resolution on Linux hosts:

```yaml
extra_hosts:
  - "host.docker.internal:host-gateway"

```

This mapping is explicitly referenced in [[`docs/env/03-outbound-proxies.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md) under the Docker networking section.

### Configure Environment Variables

Set `PROXY_URL` pointing to your host-side proxy port. Here is a complete production-ready [`docker-compose.yml`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml) example:

```yaml
version: "3.9"
services:
  freellmapi:
    image: ghcr.io/tashfeenahmed/freellmapi:latest
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      PROXY_URL: socks5h://host.docker.internal:7890
      NO_PROXY: "localhost,127.0.0.1,api.internal"
    extra_hosts:
      - "host.docker.internal:host-gateway"

```

The `PROXY_URL` variable takes precedence over dashboard settings, ensuring consistent routing behavior. The `NO_PROXY` variable excludes specified hosts from proxy traversal, which is useful for internal APIs that must not traverse the external proxy.

### Enable LAN Access on the Host Proxy

Most desktop proxy clients default to binding only on `127.0.0.1`. You must enable the **Allow LAN** setting (or equivalent, such as `allow-lan: true` in Clash configuration files) so the Docker container can connect via `host.docker.internal`. Without this setting, the container will receive connection refused errors when attempting to reach the proxy.

## Alternative Docker Run Command

If you prefer command-line deployment without Compose, use the `--add-host` flag:

```bash
docker run -d \
  -p 3001:3001 \
  -e PROXY_URL=socks5h://host.docker.internal:7890 \
  -e NO_PROXY=localhost,127.0.0.1 \
  --add-host=host.docker.internal:host-gateway \
  --name freellmapi \
  ghcr.io/tashfeenahmed/freellmapi:latest

```

This command achieves the same network configuration as the Compose example, mapping the host gateway and setting the proxy environment variables at runtime.

## Key Source Files

Reference these repository files for implementation specifics:

- **[[`docs/env/03-outbound-proxies.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/env/03-outbound-proxies.md)** – Complete reference for proxy environment variables, precedence rules, and Docker-specific networking constraints
- **[[`docs/install.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/install.md)** – Explanation of the `127.0.0.1` isolation issue and LAN binding requirements
- **[[`docs/deployment/01-docker.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/deployment/01-docker.md)](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/deployment/01-docker.md)** – Docker deployment patterns and proxy troubleshooting
- **[[`docker-compose.yml`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml)](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml)** – Official service definition template
- **[`Dockerfile`](https://github.com/tashfeenahmed/freellmapi/blob/main/Dockerfile)** – Container build specification including proxy-capable HTTP client libraries

## Summary

- FreeLLMAPI uses a strict precedence hierarchy where the `PROXY_URL` environment variable overrides all other proxy settings
- Docker containers cannot reach the host via `127.0.0.1`; use `host.docker.internal` with the `extra_hosts` mapping instead
- Supported proxy schemes include `http`, `https`, `socks4`, `socks4a`, `socks5`, and `socks5h` (prefer `socks5h` for remote DNS resolution)
- Host-side proxy clients must enable LAN access to accept connections from the Docker network
- `NO_PROXY` accepts comma-separated hostnames to bypass the proxy for internal endpoints

## Frequently Asked Questions

### Why does my proxy configuration work locally but fail in Docker?

Local development runs on the host network where `127.0.0.1` resolves to your machine. Inside a Docker container, `127.0.0.1` refers to the container's own loopback interface. You must use `host.docker.internal` to reach the host, and you must add the `--add-host` or `extra_hosts` mapping to enable this DNS name on Linux systems.

### What is the difference between `socks5` and `socks5h`?

`socks5` resolves domain names locally using the container's DNS before sending traffic through the proxy, while `socks5h` delegates DNS resolution to the proxy server. Use `socks5h` when operating behind restrictive firewalls that block DNS queries or when you require the proxy to handle all name resolution.

### Can I configure the proxy through the web dashboard instead of environment variables?

Yes, the dashboard at **Keys → Outbound proxy** supports proxy configuration, but the `PROXY_URL` environment variable takes precedence. For Docker deployments, environment variables are the recommended approach because they persist across container recreations and are easier to version control in your [`docker-compose.yml`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml) file.

### How do I verify that traffic is routing through the proxy?

Check your proxy client's connection logs for entries originating from the Docker subnet (typically `172.x.x.x` or `192.168.x.x`). You can also test by setting `NO_PROXY` to a specific test domain and confirming that requests to that domain bypass the proxy while all other traffic routes through it, confirming the configuration hierarchy is functioning correctly.