Environment Variables That Control FreeLLMAPI Behavior: Complete Configuration Guide

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

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

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

# 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 and 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_: Per-provider daily quotas (e.g., PROVIDER_DAILY_REQUEST_CAP_OPENAI). The ratelimit service in server/src/services/ratelimit.ts reads these to enforce tiered limits.

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.

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

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 and 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 and relaxes validation checks.

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 and 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 to verify signed catalog updates.

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:

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:

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

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 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.
• Rate limiting uses both global (PROXY_RATE_LIMIT_RPM) and per-provider (PROVIDER_DAILY_REQUEST_CAP_*) variables parsed by 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.

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, 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 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, while DEV_MODE is a FreeLLMAPI-specific toggle that enables diagnostic scripts (like routing-sim.ts) and relaxes input validation for local testing. Production deployments should set NODE_ENV=production and DEV_MODE=false.

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