How to Configure a Proxy URL for FreeLLMAPI Docker Deployment

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 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), 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) and [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 to enable host.docker.internal resolution on Linux hosts:

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) 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 example:

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:

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) – 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) – 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) – Docker deployment patterns and proxy troubleshooting
• [docker-compose.yml](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml) – Official service definition template
• 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 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.

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