.env.example

# ──────────────────────────────────────────────────────────────────────────────
# API Gateway — Environment Configuration
# Copy to .env and uncomment/edit the values you want to override.
# All settings below have sensible defaults in code; only set what you need.
# ──────────────────────────────────────────────────────────────────────────────

# ── Infrastructure ─────────────────────────────────────────────────────────────

# 64-char hex key used to encrypt provider API keys at rest.
# Generate with:  node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# ENCRYPTION_KEY=

# Docker only: which host interface the container's port is published on.
# Defaults to 127.0.0.1, so the dashboard/API is reachable only from the
# machine running Docker. To open it to other devices on your LAN (e.g. a
# Raspberry Pi reached at http://192.168.1.x:3001), set HOST_BIND=0.0.0.0.
# Only do this on a trusted network — the proxy is single-user and guarded
# only by the unified API key.
# HOST_BIND=0.0.0.0

# Server port (default: 3001). Used by both the server and docker-compose.
# PORT=3001

# Comma-separated extra origins allowed to call the API from a browser.
# localhost:5173, 127.0.0.1:5173, [::1]:5173 are allowed by default for the
# Vite dev dashboard. Only set this if you serve the dashboard from a
# different host than the API (e.g. http://my-server.local).
# DASHBOARD_ORIGINS=http://my-server.local,http://192.168.1.50

# Set to "1" or "true" when running behind a reverse proxy (nginx, Caddy, etc.)
# so the server trusts X-Forwarded-For / X-Forwarded-Proto headers.
# TRUST_PROXY=

# Absolute path to the Vite client build output. Only needed when serving
# the dashboard from the same process as the API.
# CLIENT_DIST=

# Node environment. Set to "production" to disable dev-only features.
# NODE_ENV=development

# ── Rate Limiting ──────────────────────────────────────────────────────────────

# Global rate limit (requests per minute) applied per API key.
# Leave unset for unlimited.
# PROXY_RATE_LIMIT_RPM=

# ── Resilience — Provider Fast-Fail ────────────────────────────────────────────
# Settings also configurable from the Settings page (feature-settings registry).

# Skip an entire provider when ≥N distinct models return 5xx (default: true)
# PROVIDER_FASTFAIL_ENABLED=true

# Number of distinct model failures to trigger fast-fail (default: 2)
# PROVIDER_FASTFAIL_THRESHOLD=2

# ── Resilience — Heartbeat ─────────────────────────────────────────────────────

# Enable periodic health-check pings to each provider (default: false)
# HEARTBEAT_ENABLED=false

# Minutes between heartbeat ping cycles (default: 10)
# HEARTBEAT_INTERVAL_MIN=10

# Max minutes since last user request for pings to fire (default: 15)
# HEARTBEAT_ACTIVITY_WINDOW_MIN=15

# Timeout per heartbeat ping in milliseconds (default: 10000)
# HEARTBEAT_TIMEOUT_MS=10000

# Random stagger between pings in milliseconds (default: 2000)
# HEARTBEAT_STAGGER_MS=2000

# ── Sessions ───────────────────────────────────────────────────────────────────

# Route all requests in a conversation to the same model (default: false)
# STICKY_SESSION_ENABLED=false

# Inject a conversation summary when the router switches models mid-session.
# Options: off | on_model_switch  (default: off)
API_GATEWAY_CONTEXT_HANDOFF=on_model_switch


# ── Degradation Engine ─────────────────────────────────────────────────────────
# The degradation engine tracks per-model penalty scores that decay over time.
# Penalties reduce a model's routing score, making the router prefer healthier models.

# Half-life (minutes) for each error severity tier's penalty decay.
# DEGRADE_MINOR_HALF_LIFE_MIN=2
# DEGRADE_MAJOR_HALF_LIFE_MIN=15
# DEGRADE_CRITICAL_HALF_LIFE_MIN=60

# Number of consecutive failures that trigger the critical tier (default: 3)
# DEGRADE_CRITICAL_THRESHOLD=3

# Fraction of penalty removed per successful request, 0–1 (default: 0.3 = 30%)
# DEGRADE_SUCCESS_RECOVERY=0.3

# Upper bound for accumulated penalty score (default: 100)
# DEGRADE_MAX_PENALTY=100

# Severity weights — how much each error tier adds to the penalty.
# DEGRADE_MINOR_WEIGHT=1.0
# DEGRADE_MAJOR_WEIGHT=3.0
# DEGRADE_CRITICAL_WEIGHT=6.0

# Compound factor — multiplier for consecutive failures (default: 1.5)
# DEGRADE_COMPOUND_FACTOR=1.5

# Dampening strength — softens the penalty curve (default: 50)
# DEGRADE_DAMP_STRENGTH=50

# Boost range — multiplier applied after degradation (default: 0.1–100)
# DEGRADE_BOOST_MIN=0.1
# DEGRADE_BOOST_MAX=100.0

# ── Analytics & Data ──────────────────────────────────────────────────────────

# How many days of request analytics to keep (default: 90)
# REQUEST_ANALYTICS_RETENTION_DAYS=90

# Hard cap on request log rows; oldest are pruned when exceeded (default: 100000)
# REQUEST_ANALYTICS_MAX_ROWS=100000