# How Environment Variables Control FreeLLMAPI Behavior: Complete Configuration Guide

> Discover how to control FreeLLMAPI behavior using over 20 environment variables. Configure server binding, encryption, rate limiting, and more with this complete guide.

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

---

**FreeLLMAPI uses 20+ environment variables to configure server binding, encryption, rate limiting, analytics retention, and feature toggles, with all settings loaded at startup from [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts) via dotenv.**

FreeLLMAPI is a self-hosted LLM API gateway that relies on environment variables for runtime configuration. According to the tashfeenahmed/freellmapi source code, these variables control everything from cryptographic operations to proxy routing and analytics retention, with defaults defined in `/.env.example`.

## Bootstrap and Server Configuration

The server initialization process reads several core variables to determine where and how to listen for connections.

**`FREEAPI_ENV_PATH`** specifies the path to the `.env` file loaded on startup. If omitted, the server defaults to `./.env` in the project root. In [`server/src/env.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/env.ts), the application calls `dotenv.config()` using this path to populate the runtime environment.

**`PORT`** and **`HOST`** control the HTTP server binding. `PORT` defaults to `3001`, while `HOST` defaults to `::` (IPv6 wildcard). These are read in [`server/src/index.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/index.ts) when the Express server starts listening.

**`NODE_ENV`** determines production versus development behavior. When set to `production`, the cryptographic utilities in [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts) disable insecure debugging helpers and enforce stricter validation.

**`DEV_MODE`** enables extra diagnostics when set to `"true"`. This activates the routing-simulation script at [`server/src/scripts/routing-sim.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/scripts/routing-sim.ts), which injects dummy keys and enables verbose logging for local testing.

## Security and Encryption

Cryptographic operations and dashboard access rely on specific environment variables for secure operation.

**`ENCRYPTION_KEY`** must be a 64-character hexadecimal string. The server refuses to start without this key because [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts) uses it for encrypting payloads and request authentication. The key is validated at startup to ensure it meets the length and format requirements.

**`DASHBOARD_ORIGINS`** configures CORS for the web UI. Provide a comma-separated list of allowed origins (e.g., `https://admin.example.com,http://localhost:3000`). This variable is read in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) when configuring Express middleware.

## Proxy and Rate Limiting

Outgoing LLM requests pass through a proxy layer with configurable rate limits to protect downstream APIs.

**`PROXY_URL`** specifies the base URL of an upstream proxy that forwards LLM requests. The proxy library in [`server/src/lib/proxy.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/proxy.ts) reads this value to determine the forwarding destination.

**`PROXY_RATE_LIMIT_RPM`** sets the global maximum requests per minute the proxy will accept. Set this to `"0"` to disable rate limiting entirely. This threshold is enforced by the middleware in [`server/src/middleware/rateLimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/middleware/rateLimit.ts).

**`PROVIDER_DAILY_REQUEST_CAP_<PLATFORM>`** defines provider-specific daily caps. For example, `PROVIDER_DAILY_REQUEST_CAP_OPENAI=10000` limits OpenAI requests to 10,000 per day. The `ratelimit` service in [`server/src/services/ratelimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/ratelimit.ts) reads these variables dynamically based on the active provider name.

## Analytics and Data Retention

Request logging behavior is controlled by two retention variables.

**`REQUEST_ANALYTICS_RETENTION_DAYS`** specifies how many days to retain request analytics data before automatic purging occurs.

**`REQUEST_ANALYTICS_MAX_ROWS`** sets the maximum rows per analytics table. Set this to `"0"` to disable analytics collection entirely, preventing any request logging to the database. Both variables are processed in [`server/src/services/request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/request-retention.ts).

## Feature Toggles and Context Management

Several boolean and enum-style variables toggle specific features.

**`FREELLMAPI_CONTEXT_HANDOFF`** controls conversation context persistence when switching models. Acceptable values are `"always"`, `"on_model_switch"`, or `"off"`. The context-handoff service at [`server/src/services/context-handoff.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/context-handoff.ts) reads this on line 28 to determine whether to carry forward conversation state.

**`CATALOG_SYNC_DISABLED`** disables remote catalog synchronization when set to `"1"`. This is useful in air-gapped environments where the server cannot reach external networks.

**`CATALOG_BASE_URL`** and **`CATALOG_PUBKEY`** configure the remote model catalog sync. The base URL defaults to the embedded catalog, while the PEM-encoded public key verifies the signed catalog integrity. These are used in [`server/src/services/catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/catalog-sync.ts).

**`CLIENT_DIST`** specifies the path to the compiled client bundle. If omitted, the server serves the embedded `dist` folder. This is checked in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) when configuring static file serving.

**`PREMIUM_SITE_URL`** provides the URL for the premium subscription page, referenced in [`server/src/routes/premium.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/premium.ts).

## Production Configuration Examples

### Minimal Production Environment

Create a `.env` file in the project root with these essential variables:

```dotenv
FREEAPI_ENV_PATH=.env
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 Mode Setup

Enable debugging utilities and use a dummy encryption key for local testing:

```bash
export DEV_MODE=true
export ENCRYPTION_KEY=$(printf '0%.0s' {1..64})
npm run dev

```

### Disabling Analytics

To completely disable request logging:

```dotenv
REQUEST_ANALYTICS_MAX_ROWS=0

```

### Air-Gapped Deployment

Disable catalog synchronization and use local assets only:

```dotenv
CATALOG_SYNC_DISABLED=1
CLIENT_DIST=/opt/freellmapi/static

```

## Summary

- **Core configuration** (`PORT`, `HOST`, `FREEAPI_ENV_PATH`) controls server binding and environment file location 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).
- **Security** (`ENCRYPTION_KEY`, `DASHBOARD_ORIGINS`) enforces encryption and CORS policies, with the encryption key required for server startup.
- **Rate limiting** (`PROXY_RATE_LIMIT_RPM`, `PROVIDER_DAILY_REQUEST_CAP_*`) protects downstream APIs through the ratelimit service and proxy middleware.
- **Analytics** (`REQUEST_ANALYTICS_*`) can be disabled by setting max rows to `0` or configured for specific retention periods.
- **Features** (`FREELLMAPI_CONTEXT_HANDOFF`, `CATALOG_SYNC_DISABLED`, `DEV_MODE`) toggle context persistence, catalog updates, and diagnostic modes.

## Frequently Asked Questions

### What happens if ENCRYPTION_KEY is not configured?

The server will fail to start. The [`server/src/lib/crypto.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/lib/crypto.ts) module validates that `ENCRYPTION_KEY` exists and is exactly 64 hexadecimal characters; without it, cryptographic primitives cannot initialize, causing the process to exit immediately.

### How do I disable request analytics completely?

Set `REQUEST_ANALYTICS_MAX_ROWS=0` in your environment. The [`request-retention.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/request-retention.ts) service checks this value and skips all database writes for analytics when set to zero, effectively disabling the feature without modifying code.

### Can FreeLLMAPI run without syncing the remote model catalog?

Yes. Set `CATALOG_SYNC_DISABLED=1` to prevent the [`catalog-sync.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/catalog-sync.ts) service from fetching remote updates. This is recommended for air-gapped deployments where external network access is restricted, though you may need to manually update the local catalog files.

### How do provider-specific rate limits work?

Variables like `PROVIDER_DAILY_REQUEST_CAP_OPENAI` or `PROVIDER_DAILY_REQUEST_CAP_ANTHROPIC` set daily quotas per provider. The [`ratelimit.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/ratelimit.ts) service constructs the environment variable name dynamically based on the provider identifier, reads the integer value, and rejects requests once the daily cap is reached.