# Environment Variables That Control FreeLLMAPI Behavior: Complete Configuration Guide

> Discover the environment variables that control FreeLLMAPI behavior. Configure HTTP server, encryption, rate limiting, and more with this complete guide.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: complete-configuration-guide
- Published: 2026-06-22

---

**FreeLLMAPI reads eighteen distinct environment variables to configure its HTTP server, encryption layer, rate limiting, analytics retention, and model catalog synchronization, with all values loaded via `dotenv` in [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts) at startup.**

The `tashfeenahmed/freellmapi` repository uses a comprehensive environment-based configuration system that allows operators to tune security, performance, and feature availability without modifying source code. Understanding which environment variables control FreeLLMAPI behavior is essential for production deployments, development debugging, and air-gapped installations. All variables are optional in development but several—particularly `ENCRYPTION_KEY`—are mandatory for secure operation.

## Core Server Configuration

The server’s network binding and runtime mode are controlled by four fundamental variables defined in [`server/src/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/index.ts) and [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts).

- **PORT**: HTTP port the API server binds to. Defaults to `3001` if omitted.
- **HOST**: Host address to bind. Defaults to `::` (IPv6 any-address) for universal listening.
- **FREEAPI_ENV_PATH**: Absolute or relative path to the `.env` file loaded at startup. If unset, the process looks for `.env` in the working directory.
- **NODE_ENV**: Runtime mode string (`production` or `development`) that affects cryptographic behavior in [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts) and logging verbosity.

```bash

# Bind to specific interface and port

export PORT=8080
export HOST=0.0.0.0
export NODE_ENV=production

```

## Security and Encryption Settings

Cryptographic operations and request authentication depend on a single critical variable processed in [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts).

- **ENCRYPTION_KEY**: A 64-character hexadecimal string used for AES-256-GCM payload encryption and request signing. The server refuses to start if this key is missing or malformed because all cryptographic primitives depend on it.
- **NODE_ENV**: When set to `production`, disables insecure debugging helpers and enforces stricter key validation.

```dotenv

# 64-character hex key (256 bits)

ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

```

## Proxy and Rate Limiting Controls

Outbound LLM traffic routing and throttling are governed by variables read in [`server/src/lib/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/proxy.ts) and [`server/src/middleware/rateLimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/middleware/rateLimit.ts).

- **PROXY_URL**: Base URL of an upstream proxy that forwards LLM requests. Required when running behind a corporate gateway or external load balancer.
- **PROXY_RATE_LIMIT_RPM**: Global rate limit in requests per minute for the proxy layer. Set to `"0"` to disable throttling entirely.
- **PROVIDER_DAILY_REQUEST_CAP_<PLATFORM>**: Per-provider daily quotas (e.g., `PROVIDER_DAILY_REQUEST_CAP_OPENAI`). The `ratelimit` service in [`server/src/services/ratelimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/ratelimit.ts) reads these to enforce tiered limits.

```dotenv
PROXY_URL=https://proxy.internal.company.com
PROXY_RATE_LIMIT_RPM=120
PROVIDER_DAILY_REQUEST_CAP_OPENAI=10000
PROVIDER_DAILY_REQUEST_CAP_ANTHROPIC=5000

```

## Analytics and Data Retention

Request logging persistence is configurable via two variables consumed by [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts).

- **REQUEST_ANALYTICS_RETENTION_DAYS**: Integer specifying how many days to retain request analytics before automatic purging.
- **REQUEST_ANALYTICS_MAX_ROWS**: Maximum row count per analytics table. Setting this to `"0"` disables analytics collection completely, reducing disk I/O.

```dotenv
REQUEST_ANALYTICS_RETENTION_DAYS=30
REQUEST_ANALYTICS_MAX_ROWS=10000

```

## Feature Toggles and Context Management

Advanced conversational and catalog behaviors are controlled by feature flags in [`server/src/services/context-handoff.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/context-handoff.ts) and [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts).

- **FREELLMAPI_CONTEXT_HANDOFF**: Determines conversation state preservation when switching models. Acceptable values are `"always"` (persist across all switches), `"on_model_switch"` (preserve only when explicitly changing models), or `"off"` (stateless).
- **CATALOG_SYNC_DISABLED**: Set to `"1"` to disable periodic remote catalog synchronization. Useful for air-gapped environments or pinned model versions.
- **DEV_MODE**: When set to `"true"`, enables diagnostic endpoints like the routing simulator in [`server/src/scripts/routing-sim.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/scripts/routing-sim.ts) and relaxes validation checks.

```dotenv
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch
CATALOG_SYNC_DISABLED=0
DEV_MODE=false

```

## Web Dashboard and Static Assets

CORS policies, UI hosting, and catalog verification rely on variables processed in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) and [`server/src/routes/premium.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts).

- **DASHBOARD_ORIGINS**: Comma-separated list of origins allowed to embed the dashboard via CORS headers.
- **CLIENT_DIST**: Filesystem path to the compiled client bundle. If omitted, the server serves the embedded `dist` folder.
- **PREMIUM_SITE_URL**: External URL for the premium subscription page linked from the dashboard.
- **CATALOG_BASE_URL**: Remote endpoint for model catalog synchronization. Defaults to the embedded catalog if unset.
- **CATALOG_PUBKEY**: PEM-encoded public key used by [`catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/catalog-sync.ts) to verify signed catalog updates.

```dotenv
DASHBOARD_ORIGINS=https://admin.example.com,https://localhost:3000
CLIENT_DIST=/var/www/freellmapi/dist
PREMIUM_SITE_URL=https://billing.example.com/premium
CATALOG_BASE_URL=https://catalog.freellmapi.dev/v1

```

## Configuration Examples

### Minimal Production Deployment

This `.env` configuration provides a secure, monitored production instance with rate limiting and analytics enabled:

```dotenv
PORT=8080
HOST=0.0.0.0
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
PROXY_URL=https://my-proxy.example.com
PROXY_RATE_LIMIT_RPM=120
PROVIDER_DAILY_REQUEST_CAP_OPENAI=10000
REQUEST_ANALYTICS_RETENTION_DAYS=30
REQUEST_ANALYTICS_MAX_ROWS=5000
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch

```

### Development and Testing Mode

Enable verbose diagnostics and use a dummy encryption key for local testing:

```bash
export DEV_MODE=true
export ENCRYPTION_KEY=$(printf '0%.0s' {1..64})  # 64 zeroes for tests

npm run dev

```

When `DEV_MODE` is `"true"`, the routing-simulation script ([`server/src/scripts/routing-sim.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/scripts/routing-sim.ts)) injects the dummy key and enables verbose request logging.

### Air-Gapped or Offline Environments

Disable remote catalog fetching and reduce analytics retention for isolated networks:

```dotenv
CATALOG_SYNC_DISABLED=1
REQUEST_ANALYTICS_MAX_ROWS=1000
CATALOG_BASE_URL=  # Intentionally empty to force embedded catalog usage

```

The `catalog-sync` service checks `CATALOG_SYNC_DISABLED` at line 483 of [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts) and skips network initialization when set.

## Summary

- **FreeLLMAPI** requires `ENCRYPTION_KEY` (64-character hex) for cryptographic operations; without it, the process exits on startup.
- Network binding is controlled by `PORT` (default 3001) and `HOST` (default `::`), loaded in [`server/src/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/index.ts).
- Rate limiting uses both global (`PROXY_RATE_LIMIT_RPM`) and per-provider (`PROVIDER_DAILY_REQUEST_CAP_*`) variables parsed by [`server/src/services/ratelimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/ratelimit.ts).
- Analytics persistence is toggled via `REQUEST_ANALYTICS_MAX_ROWS`; set to `0` to disable logging entirely.
- Context handoff behavior is configured through `FREELLMAPI_CONTEXT_HANDOFF` with three modes: `always`, `on_model_switch`, or `off`.
- Development features and routing simulation require `DEV_MODE=true`, which relaxes security checks in [`server/src/scripts/routing-sim.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/scripts/routing-sim.ts).

## Frequently Asked Questions

### What happens if ENCRYPTION_KEY is missing or invalid?

The server immediately terminates during initialization. According to [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts), the encryption layer requires a 64-character hexadecimal string to derive AES-256-GCM keys; startup will fail with a cryptographic initialization error if the variable is absent, too short, or contains non-hex characters.

### How do I disable analytics collection entirely?

Set `REQUEST_ANALYTICS_MAX_ROWS=0` in your environment. The [`request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/request-retention.ts) service interprets this value as a directive to skip database writes for request logs, effectively disabling analytics without affecting core LLM proxy functionality.

### Can I run FreeLLMAPI without an internet connection?

Yes. Set `CATALOG_SYNC_DISABLED=1` to prevent the catalog-sync service from attempting remote fetches, and ensure `CATALOG_BASE_URL` is unset so the server falls back to the embedded model catalog. You should also omit `PROXY_URL` if your deployment does not use an external forward proxy.

### What is the difference between NODE_ENV and DEV_MODE?

`NODE_ENV` is a standard Node.js convention that primarily affects cryptographic strictness and logging levels in [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts), while `DEV_MODE` is a FreeLLMAPI-specific toggle that enables diagnostic scripts (like [`routing-sim.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/routing-sim.ts)) and relaxes input validation for local testing. Production deployments should set `NODE_ENV=production` and `DEV_MODE=false`.