How to Configure Environment Variables for FreeLLMAPI: Complete Setup Guide

Set your ENCRYPTION_KEY and PORT in a .env file at the repository root, or point to a custom path with FREEAPI_ENV_PATH.

The FreeLLMAPI open-source project reads all runtime configuration from environment variables loaded via dotenv. According to the tashfeenahmed/freellmapi source code, the server locates your settings through server/src/env.ts, which searches for a .env file by default or respects the FREEAPI_ENV_PATH override for custom deployments.

This guide covers every configuration step: creating your environment file, generating required secrets, tuning network and proxy settings, and enabling optional features like caching and compression.

---

Creating the .env File

FreeLLMAPI expects environment variables in a .env file at the repository root. The official template at .env.example documents every supported variable with defaults and deployment recommendations.

To get started:

1. Copy the template:

   cp .env.example .env

2. Edit .env with your preferred values.

The loader in server/src/env.ts processes this file at startup:

// server/src/env.ts
import dotenv from 'dotenv';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

dotenv.config({ 
  path: process.env.FREEAPI_ENV_PATH ?? path.resolve(__dirname, '../../.env') 
});

When FREEAPI_ENV_PATH is unset, the code falls back to ../../.env—two levels above the compiled server/dist/ directory, placing it at your repository root.

---

Required Variables for FreeLLMAPI Configuration

Every production deployment needs two core settings.

ENCRYPTION_KEY

This 64-character hex string encrypts stored provider API keys in the database. Generate one with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Example output: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Without this key, FreeLLMAPI refuses to start in production mode.

PORT

The HTTP port for the unified OpenAI-compatible endpoint. Default is 3001.

Minimal working .env:

ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
PORT=3001

---

Network and Proxy Settings

HOST and HOST_BIND

Variable	Purpose	Default
HOST	Interface the server binds to	:: (dual-stack IPv6/IPv4)
HOST_BIND	Docker-published host for LAN exposure	0.0.0.0

Use HOST=:: to accept connections on all interfaces. In Docker Compose, pair with HOST_BIND=0.0.0.0.

Proxy Configuration

Route provider requests through an outbound proxy:

PROXY_URL=socks5h://127.0.0.1:1080
NO_PROXY=localhost,127.0.0.1,.internal.corp
FREEAPI_PROXY_LOCAL_DESTINATIONS=true

• PROXY_URL: Supports http://, https://, socks5://, and socks5h:// schemes.
• NO_PROXY: Comma-separated domains/IPs that bypass the proxy.
• FREEAPI_PROXY_LOCAL_DESTINATIONS: Set to true to allow proxying local endpoints like Ollama (normally blocked for security).

---

Provider-Specific Tuning

Override defaults per AI platform using prefixed variables:

# Timeout in milliseconds

PROVIDER_TIMEOUT_NVIDIA=300000
PROVIDER_TIMEOUT_OLLAMA=60000

# Daily request caps (0 = unlimited)

PROVIDER_DAILY_REQUEST_CAP_OPENROUTER=50
PROVIDER_DAILY_REQUEST_CAP_OPENAI=0

These caps help manage costs across multiple provider accounts.

---

Optional Performance Features

Response Caching

Enable in-memory caching for identical non-streaming requests:

RESPONSE_CACHE=true

Repeated prompts return instantly without hitting provider APIs.

Prompt Compression

FREELLMAPI_COMPRESSION=standard

Modes: off | lossless | standard | aggressive. Reduces token usage at potential quality trade-offs.

Rate Limit Adjustments

PROXY_RATE_LIMIT_RPM=60
ADMIN_RATE_LIMIT_RPM=1000

Raise these if you hit 429 errors under heavy load.

---

Docker Compose Deployment

Reference your .env in docker-compose.yml:

services:
  freellmapi:
    image: ghcr.io/freellmapi/freellmapi:latest
    ports:
      - "3001:3001"
    env_file: .env
    volumes:
      - ./data:/app/server/data
    restart: unless-stopped

Docker automatically injects variables from env_file into the container's environment.

---

Desktop and Custom Paths

The FreeLLMAPI desktop bundle sets FREEAPI_ENV_PATH to its internal configuration directory. The same server/src/env.ts loader handles this transparently—your settings persist across app updates.

To use a completely custom location (e.g., /etc/freellmapi/config):

export FREEAPI_ENV_PATH=/etc/freellmapi/config
npm run start

---

Troubleshooting Common Configuration Issues

Symptom	Cause	Solution
Server exits with "ENCRYPTION_KEY required"	Missing or invalid encryption key	Generate 64-character hex key as shown above
Providers unreachable behind proxy	NO_PROXY too broad or FREEAPI_PROXY_LOCAL_DESTINATIONS disabled	Trim NO_PROXY list, set FREEAPI_PROXY_LOCAL_DESTINATIONS=true
Port already in use	3001 occupied by another service	Change PORT and update Docker port mapping
Cache never hits	RESPONSE_CACHE not enabled	Add RESPONSE_CACHE=true to .env
Rate limit errors on valid keys	Default RPM caps too restrictive	Increase PROXY_RATE_LIMIT_RPM or ADMIN_RATE_LIMIT_RPM

---

Summary

• FreeLLMAPI environment variables live in a .env file loaded by server/src/env.ts at startup
• ENCRYPTION_KEY (64 hex chars) and PORT are the only strictly required variables
• Use FREEAPI_ENV_PATH to relocate your config file for Docker, desktop, or system-wide deployments
• Proxy settings, provider timeouts, daily caps, caching, and compression all tune via environment variables
• Reference .env.example for the complete variable list and defaults

---

Frequently Asked Questions

Where does FreeLLMAPI look for the .env file?

By default, server/src/env.ts resolves ../../.env relative to the compiled output—placing it at your repository root. Set FREEAPI_ENV_PATH to override this location for custom deployments or desktop installations.

How do I generate a valid ENCRYPTION_KEY?

Run node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" in any Node.js environment. This produces the required 64-character hexadecimal string. Store it securely; losing this key renders encrypted provider credentials unrecoverable.

Why are my proxy settings not working with local Ollama?

FreeLLMAPI blocks proxying to local destinations by default for security. Add FREEAPI_PROXY_LOCAL_DESTINATIONS=true to your .env, and ensure localhost or 127.0.0.1 are not in your NO_PROXY list.

Can I use different .env files for development and production?

Yes. Create separate files (e.g., .env.development, .env.production) and launch with FREEAPI_ENV_PATH=/path/to/specific.env. This pattern works for Docker, shell scripts, or process managers like PM2.

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