How Environment Variables Control FreeLLMAPI Behavior: Complete Configuration Guide

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 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, 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 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 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, 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 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 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 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.

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 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.

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 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.

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 when configuring static file serving.

PREMIUM_SITE_URL provides the URL for the premium subscription page, referenced in server/src/routes/premium.ts.

Production Configuration Examples

Minimal Production Environment

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

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:

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

Disabling Analytics

To completely disable request logging:

REQUEST_ANALYTICS_MAX_ROWS=0

Air-Gapped Deployment

Disable catalog synchronization and use local assets only:

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 and 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 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 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 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 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.

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