# How to Configure Environment Variables for FreeLLMAPI: Complete Setup Guide

> Configure environment variables for FreeLLMAPI effortlessly. Learn how to set ENCRYPTION_KEY and PORT using a .env file or a custom path for seamless setup.

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

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/.env.example) documents every supported variable with defaults and deployment recommendations.

To get started:

1. Copy the template:

   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your preferred values.

The loader in [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts) processes this file at startup:

```typescript
// 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:

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

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

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

```ini

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

```ini
RESPONSE_CACHE=true

```

Repeated prompts return instantly without hitting provider APIs.

### Prompt Compression

```ini
FREELLMAPI_COMPRESSION=standard

```

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

### Rate Limit Adjustments

```ini
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/docker-compose.yml):

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

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