.env.example

# Server Configuration
SERVER_HOST=localhost
SERVER_PORT=1400
FLASK_ENV=development

# Missing upstream client identity defaults to Codex on every provider route,
# including free pools and roleplay. Caller-supplied headers always win.
UPSTREAM_DEFAULT_USER_AGENT=codex-cli
UPSTREAM_DEFAULT_ORIGINATOR=codex_cli_rs

# Local SQLite state. On Vercel and Cloudflare Containers these files are
# ephemeral unless you explicitly wire durable external storage.
AUTH_DB_PATH=instance/auth.sqlite3
RATE_LIMIT_DB_PATH=instance/rate_limits.sqlite3
MODEL_REGISTRY_DB_PATH=instance/model_registry.sqlite3
CONNECTION_PROFILES_DB_PATH=instance/workbench.sqlite3
# Optional durable PostgreSQL control plane (users, quotas, routing, saved profiles).
# Leave blank for local SQLite. Configure through your secret manager in production.
CONTROL_PLANE_DATABASE_URL=
# Fernet key for offline encrypted backups; never commit a real key.
CONTROL_PLANE_BACKUP_KEY=
# Fixed trusted Worker origin for the authenticated operator workbench (no path).
WORKBENCH_WORKER_URL=
SQLITE_TIMEOUT_SECONDS=10
SQLITE_BUSY_TIMEOUT_MS=10000

# Free-only chat pools. Account-tier providers must use unbilled free accounts.
# Optional explicit free-tier assertion: FREE_ROUTE_FREE_TIER_PROVIDERS=groq,gemini
FREE_ROUTE_FREE_TIER_PROVIDERS=
# New destinations are opt-in even if their keys already exist. See docs/free-provider-setup.md.
# Options: mistral,workersai,zai,orcarouter,bazaarlink,llm7
FREE_ROUTE_EXTRA_PROVIDERS=
# Workers AI requires a separate Workers Free account and scoped inference token.
FREE_ROUTE_WORKERSAI_ACCOUNT_ID=
MISTRAL_API_KEY=
WORKERSAI_API_KEY=
ZAI_API_KEY=
ORCAROUTER_API_KEY=
BAZAARLINK_API_KEY=
LLM7_API_KEY=
# Optional server-owned priority; unknown names are ignored, others remain fallbacks.
FREE_ROUTE_PROVIDER_ORDER=groq,opencode,aihubmix,gemini,openrouter

# Runtime tuning
LOG_LEVEL=INFO
GUNICORN_WORKERS=1
GUNICORN_THREADS=8
GUNICORN_TIMEOUT=120
GUNICORN_GRACEFUL_TIMEOUT=30
RATE_LIMIT_ENABLED=true
RATE_LIMIT_RPM=500
RATE_LIMIT_TPM=200000
DAILY_REQUEST_LIMIT=10000
MAX_REQUEST_BYTES=1048576
MAX_PROMPT_TOKENS=128000
MAX_OUTPUT_TOKENS=8192
OPTIMIZER_MAX_REQUEST_BYTES=16777216
OPTIMIZER_SUMMARY_TIMEOUT_SECONDS=45
GLM_AUTO_OPTIMIZE=true
GLM_AUTO_OPTIMIZE_TRIGGER_TOKENS=8000
GLM_AUTO_OPTIMIZE_KEEP_RECENT_TURNS=8
CONTEXT_ANALYSIS_CACHE_ENABLED=true
CONTEXT_ANALYSIS_CACHE_TTL_SECONDS=300
PROVIDER_USAGE_CACHE_TTL_SECONDS=60
PROVIDER_USAGE_TIMEOUT_SECONDS=8
CONTEXT_ANALYSIS_CACHE_MAX_ENTRIES=2048
PROMPT_CACHE_ENABLED=true
PROMPT_CACHE_MIN_TOKENS=1024
RATE_LIMIT_USAGE_RETENTION_SECONDS=172800
# With the Worker's D1 store: seconds between background usage syncs (1-60).
RATE_LIMIT_SYNC_SECONDS=5
MIMO_MAX_REQUEST_BYTES=16777216
MIMO_MAX_PROMPT_TOKENS=1048576
MIMO_MAX_OUTPUT_TOKENS=131072
MIMO_RATE_LIMIT_TPM=1200000
OPENCODE_MAX_REQUEST_BYTES=8388608
OPENCODE_MAX_PROMPT_TOKENS=262144
OPENCODE_MAX_OUTPUT_TOKENS=262144
OPENCODE_RATE_LIMIT_TPM=1200000
NANOGPT_RATE_LIMIT_RPM=60
NANOGPT_MAX_REQUEST_BYTES=16777216
NANOGPT_KEY_CHECK_TIMEOUT_SECONDS=5
NANOGPT_KEY_CHECK_TTL_SECONDS=300
NANOGPT_KEY_CHECK_EVERY_REQUESTS=50
NANOGPT_KEY_REJECTED_COOLDOWN_SECONDS=60
NAVYAI_MAX_REQUEST_BYTES=33554432

# Lean endpoint (/lean/v1/...) for Claude API models; see docs/lean.md.
# LEAN_ENDPOINT_ENABLED=true
# LEAN_PROMPT_TOKEN_LIMIT=99000
# LEAN_PRICE_LIMIT_BASIS=original
# LEAN_CLEAR_TRIGGER_TOKENS=80000
# LEAN_CLEAR_KEEP_TOOL_USES=3
# LEAN_CLEAR_AT_LEAST_TOKENS=20000
# LEAN_CLEAR_EXCLUDE_TOOLS=
# LEAN_CACHE_TTL=5m
# LEAN_CONDENSE_SHELL_OUTPUT=true
# LEAN_TOOL_RESULT_MAX_CHARS=100000
# LEAN_STYLE=none

# Process-local recovery for normalized transports. Fidelity-first raw routes
# remain retry- and circuit-free. The default two half-open probes support two
# concurrent Codex instances while keeping recovery pressure bounded. State
# resets on process restart and is independent in each application replica.
CIRCUIT_BREAKER_DEGRADED_FAILURES=3
CIRCUIT_BREAKER_FAILURES=5
CIRCUIT_BREAKER_COOLDOWN_SECONDS=30
CIRCUIT_BREAKER_MAX_COOLDOWN_SECONDS=300
CIRCUIT_BREAKER_HALF_OPEN_SUCCESSES=2
CIRCUIT_BREAKER_HALF_OPEN_MAX_PROBES=2

# Optional configured cost estimates in USD per one million tokens. Exact model
# IDs win, then provider wildcards, then "*". Omit this setting to leave all
# requests visibly unpriced; MultiLLM never guesses current provider prices.
# Replace these example amounts with the rates in your current provider contract.
# MODEL_PRICING_USD_PER_MILLION='{"provider:model":{"input":1.00,"output":2.00},"provider:*":{"input":1.00,"output":2.00}}'
# An entry may add a flat "request" price in USD (per image on image routes), e.g. "gguu:*":{"request":0.04}.

# Usage ledger and per-key budgets (docs/usage-and-budgets.md). Rows are written behind
# requests in batches: to D1 on Cloudflare, else to USAGE_DB_PATH (or PostgreSQL).
USAGE_LEDGER_ENABLED=true
# d1 or sql; defaults to D1 wherever the Worker provides it.
USAGE_LEDGER_BACKEND=
USAGE_DB_PATH=instance/usage.sqlite3
USAGE_LEDGER_FLUSH_SECONDS=5
USAGE_LEDGER_BATCH_SIZE=200
USAGE_LEDGER_MAX_BUFFER=10000
USAGE_LEDGER_MAX_ATTEMPTS=12
USAGE_LEDGER_RAW_RETENTION_DAYS=30
USAGE_LEDGER_ROLLUP_RETENTION_DAYS=400
USAGE_LEDGER_PRUNE_INTERVAL_SECONDS=3600
USAGE_LEDGER_SHUTDOWN_SECONDS=5
USAGE_METRICS_HYDRATE_ROWS=2000
USAGE_BUDGET_REFRESH_SECONDS=60

# Optional OTLP/HTTP JSON export of request spans and metrics; off when unset.
# Never includes prompts, outputs or keys. Headers are key=value pairs, comma-separated.
OTEL_EXPORTER_OTLP_ENDPOINT=
OTEL_EXPORTER_OTLP_HEADERS=
OTEL_SERVICE_NAME=multillm-proxy

# Automatic-route candidate order: priority (configured order) or health (recent
# success, latency and optionally price, configured order as tiebreaker).
# Per-route overrides win. See docs/status-and-health.md.
AUTO_ROUTE_ORDERING=priority
# AUTO_ROUTE_ORDERING_OVERRIDES=auto:glm-5.2=health,auto:image=priority
AUTO_ROUTE_HEALTH_HALF_LIFE_SECONDS=600
AUTO_ROUTE_LATENCY_WEIGHT=0.2
AUTO_ROUTE_COST_WEIGHT=0
AUTO_ROUTE_SCORE_MARGIN=0.05
AUTO_ROUTE_EXPLORE_EVERY=0
# Route health is written to D1 in batches when the Worker provides it.
ROUTE_HEALTH_FLUSH_SECONDS=60
ROUTE_HEALTH_PERSIST=true
# Minutes between free model-list checks. On Cloudflare the Worker's cron also reads
# KEEP_WARM and HEALTH_CHECKS_WAKE (both false) from its vars in wrangler.jsonc.
HEALTH_CHECK_INTERVAL_MINUTES=30

# Opt-in exact-match cache for deterministic chat completions (X-MultiLLM-Cache: on).
RESPONSE_CACHE_ENABLED=true
RESPONSE_CACHE_TTL_SECONDS=300
RESPONSE_CACHE_MAX_ENTRIES=512
RESPONSE_CACHE_MAX_BYTES=16777216

# Authentication
ADMIN_USERNAME=admin
ADMIN_API_KEY=your-universal-api-key
ROLEPLAY_API_KEY=your-roleplay-api-key
FLASK_SECRET_KEY=your-flask-secret-key
JWT_SECRET=your-jwt-secret-key
# Extra usernames allowed to hold administration, beside ADMIN_USERNAME.
# ADMIN_USERNAMES=deputy,auditor

# Optional dashboard single sign-on through Cloudflare Access (docs/dashboard-sso.md).
# The Worker verifies the Access token; set all three to enable it.
# CF_ACCESS_TEAM_DOMAIN=https://your-team.cloudflareaccess.com
# CF_ACCESS_AUD=your-access-application-aud-tag
# CF_ACCESS_PROOF_SECRET=at-least-32-random-characters
# Comma-separated email=username pairs, or a bare email for an account with that name.
# CF_ACCESS_ALLOWED_EMAILS=alice@example.com=alice,ops@example.com=admin
# true disables password sign-in to the dashboard; API keys are unaffected.
# DASHBOARD_SSO_ONLY=false

# Media storage and jobs (docs/media-storage.md). Signed media links, job principals and
# webhook secrets use MEDIA_SIGNING_SECRET, or FLASK_SECRET_KEY when it is unset. Set it
# as a Worker secret so the Worker can check links without waking the Container.
# MEDIA_SIGNING_SECRET=your-media-signing-secret
# Lifetime of signed media links in seconds (60 to 2592000; default 604800, seven days).
# MEDIA_LINK_TTL_SECONDS=604800
# Body limit for image and audio upload routes (default 48 MiB), and how long an image
# stored with POST /v1/media/uploads can be referenced by ID (default one day).
# MEDIA_UPLOAD_MAX_BYTES=50331648
# MEDIA_UPLOAD_TTL_SECONDS=86400

# Provider API Keys (Optional - if you want to use different keys for different providers)
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
# Optional spares, used in order after a key is refused (docs/anthropic.md).
# ANTHROPIC_API_KEY_1=
# Required only for Anthropic keys that can act on multiple workspaces.
ANTHROPIC_WORKSPACE_ID=
CEREBRAS_API_KEY=your-cerebras-api-key
XAI_API_KEY=your-xai-api-key

GOOGLE_APPLICATION_CREDENTIALS=path-to-your-google-credentials.json
GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account",...}'
PROJECT_ID=your-actual-project-id
LOCATION=your-actual-location
GOOGLE_ENDPOINT=your-endpoint

AZURE_API_KEY=your-azure-api-key
SCALEWAY_API_KEY=your-scaleway-api-key
HYPERBOLIC_API_KEY=your-hyperbolic-api-key
SAMBANOVA_API_KEY=your-sambanova-api-key
OPENROUTER_API_KEY=your-openrouter-api-key
OPENCODE_GO_API_KEY=your-opencode-go-api-key
# Optional compatibility alias: OPENCODE_API_KEY=your-opencode-go-api-key
MIMO_API_KEY=your-mimo-token-plan-api-key
NANOGPT_API_KEY=your-nanogpt-api-key
NAVYAI_API_KEY=your-navyai-api-key
AIHUBMIX_API_KEY=your-aihubmix-api-key
A6API_API_KEY=your-a6api-api-key
AIMLAPI_API_KEY=your-aimlapi-api-key
EPHONE_API_KEY=your-ephone-api-key
GGUU_API_KEY=your-gguu-api-key
# Optional compatibility alias: GGUUAI_API_KEY=your-gguu-api-key
# GGUU keys belong to one group. A Grok-image group key serves gguu-grok:grok-imagine-*.
GGUU_GROK_API_KEY=your-gguu-grok-image-group-key
# Optional compatibility alias: GGUUAI_API_KEY_GROK=your-gguu-grok-image-group-key
LATIX_API_KEY=your-latix-api-key
LINKAPI_KEY=your-linkapi-api-key
# Optional compatibility alias: LINKAPI_API_KEY=your-linkapi-api-key
CODEX_EASY_API_KEY=your-codex-easy-api-key
# Optional compatibility alias: CODEX_API_KEY=your-codex-easy-api-key
# Codex Everywhere pools (codex-everywhere.com): each key serves one group. Model IDs are
# <pool>:<model>, e.g. ce-gpt-pro:gpt-6.1-sol or ce-claude-kiro:claude-opus-5-5.
CODEX_EVERYWHERE_API_KEY_GPT_PLUS_POOL=your-ce-plus-pool-key
CODEX_EVERYWHERE_API_KEY_GPT_PRO_POOL=your-ce-pro-pool-key
CODEX_EVERYWHERE_API_KEY_GROK_HEAVY=your-ce-grok-heavy-key
CODEX_EVERYWHERE_API_KEY_CLAUDE_UNSTABLE=your-ce-claude-kiro-cheap-key
CODEX_EVERYWHERE_API_KEY_CLAUDE_KIRO=your-ce-claude-kiro-key
CODEX_EVERYWHERE_API_KEY_CLAUDE_MAX=your-ce-claude-max-key
CODEX_EVERYWHERE_API_KEY_GPT_IMAGE=your-ce-gpt-image-key
# Spare keys for any pool: append _1, _2, ... (e.g. CODEX_EVERYWHERE_API_KEY_GPT_PRO_POOL_1).
# A refused or rate-limited key rests and the next one is used.
KIMI_CODE_API_KEY=your-kimi-code-api-key
# ClinePass subscription key from app.cline.bot Settings > API Keys.
CLINE_API_KEY=your-cline-api-key
PALM_API_KEY=your-palm-api-key

# Additional credential-isolated OpenAI-compatible image relays. Provider IDs
# cannot replace built-in providers, and base_url must be a public HTTPS origin.
# Keep the configuration non-secret; put credentials in the declared env name.
# IMAGE_RELAY_PROVIDERS_JSON='{"myrelay":{"display_name":"My Relay","base_url":"https://api.example.com","backup_base_url":"https://api-backup.example.com","credential_env":"MYRELAY_API_KEY","models":["gpt-image-2"],"supports_chat":true,"supports_edits":true}}'
# MYRELAY_API_KEY=your-relay-api-key
# Cloudflare deployments may instead store all relay credentials as one secret:
# IMAGE_RELAY_API_KEYS_JSON='{"myrelay":"your-relay-api-key"}'


# OpenRouter configuration
OPENROUTER_SITE_URL=your-site-url
OPENROUTER_APP_NAME=your-app-name

# Multiple Groq API keys for token-based rate limiting (6000 tokens/minute per key)
GROQ_API_KEY_1=your-first-groq-api-key
GROQ_API_KEY_2=your-second-groq-api-key
GROQ_API_KEY_3=your-third-groq-api-key
# Add more GROQ_API_KEY_N as needed 

# Together AI API key
TOGETHER_API_KEY=your-together-api-key

# Azure API key
AZURE_API_KEY=your-azure-api-key

# Scaleway API key
SCALEWAY_API_KEY=your-scaleway-api-key

# Hyperbolic API key
HYPERBOLIC_API_KEY=your-hyperbolic-api-key

# SambaNova API key
SAMBANOVA_API_KEY=your-sambanova-api-key

# OpenRouter API key
OPENROUTER_API_KEY=your-openrouter-api-key

# Xiaomi MiMo Token Plan API key
MIMO_API_KEY=your-mimo-token-plan-api-key

# OpenCode Go API key
OPENCODE_GO_API_KEY=your-opencode-go-api-key
# Optional compatibility alias: OPENCODE_API_KEY=your-opencode-go-api-key
# Optional upstream overrides
# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1
# OPENCODE_BASE_URL=https://opencode.ai/zen/go/v1
# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1

# NanoGPT API key
NANOGPT_API_KEY=your-nanogpt-api-key
# Add more keys with increasing suffixes. The legacy NANO_GPT_KEY and
# NANO_GPT_KEY_N names are also accepted.
NANOGPT_API_KEY_1=your-second-nanogpt-api-key
# Prefer a numbered key without removing key 0 from automatic fallback.
NANOGPT_PREFERRED_KEY_INDEX=1
# Subscription-only text routing is the safe default. Set standard only when
# this account intentionally permits pay-as-you-go traffic.
NANOGPT_BILLING_MODE=subscription
# Provider selection for NanoGPT text routes: append :fast (best estimated
# completion time), :throughput (highest tokens/second), or :latency (lowest
# time to first token) to the upstream model id. These routes bypass
# subscription coverage and bill pay-as-you-go at the selected provider's rate
# plus a 5% provider-selection markup, so enabling this also forces the standard
# text endpoint. Leave empty to stay on the subscription route.
# NANOGPT_SPEED_ROUTING=fast
# Optional upstream overrides
# NANOGPT_SUBSCRIPTION_BASE_URL=https://nano-gpt.com/api/subscription
# NANOGPT_BASE_URL=https://nano-gpt.com/api
# NANOGPT_BATCH_BASE_URL=https://api.nano-gpt.com/api/v1
# NANOGPT_ORIGIN_URL=https://nano-gpt.com

# NavyAI API key
NAVYAI_API_KEY=your-navyai-api-key
# Optional upstream override
# NAVYAI_BASE_URL=https://api.navy

# AIHubMix trusted origins
# AIHUBMIX_BASE_URL=https://aihubmix.com
# AIHUBMIX_BACKUP_BASE_URL=https://api.inferera.com

# Cloudflare-native roleplay endpoint
# Provider priority is strict by tier. Kimi/GLM selection adapts within a tier.
ROLEPLAY_PROVIDER_ORDER=nanogpt,opencode,linkapi,navyai
ROLEPLAY_KIMI_MODEL=kimi-k2.6
ROLEPLAY_GLM_MODEL=glm-5.3-flash
# Optional per-provider IDs. NanoGPT subscription routing keeps full 5.3 as an
# explicit-only 2x choice and prioritizes the three 1x GLM variants.
ROLEPLAY_PROVIDER_MODELS={"nanogpt":{"glm":["z-ai/glm-5.3-flash","z-ai/glm-5.3-flash-uncensored","zai-org/glm-5.2:thinking","z-ai/glm-5.3"]},"opencode":{"glm":["glm-5.3-flash","glm-5.2","glm-5.3"]},"navyai":{"glm":"glm-5.2-venice"}}
# Optional provider-family eligibility. An explicit empty array disables a tier.
ROLEPLAY_PROVIDER_FAMILIES={"nanogpt":["glm"],"opencode":["glm","kimi"],"linkapi":["kimi"],"navyai":["glm"]}
# Optional per-provider/family context_window and max_output_tokens overrides.
ROLEPLAY_PROVIDER_LIMITS={}
ROLEPLAY_QUALITY_LATENCY_PREMIUM_PERCENT=20
ROLEPLAY_QUALITY_MIN_SAMPLES=3
ROLEPLAY_SPEED_REFERENCE_OUTPUT_TOKENS=1024
# Keep raw dialogue until this estimated-token threshold, then compact it.
ROLEPLAY_COMPACT_TRIGGER_TOKENS=128000
ROLEPLAY_COMPACT_TRIGGER_PERCENT=90
ROLEPLAY_HARD_INPUT_TOKENS=0
ROLEPLAY_MEMORY_TARGET_TOKENS=1200
ROLEPLAY_KEEP_RECENT_MESSAGES=32
ROLEPLAY_CONTEXT_REPLY_RESERVE_TOKENS=4096
ROLEPLAY_CONTEXT_SAFETY_TOKENS=1024
ROLEPLAY_MAX_REQUEST_BYTES=8388608
ROLEPLAY_MAX_STORED_BYTES=640000
ROLEPLAY_COMPACTION_MAX_TOKENS=1200
ROLEPLAY_COMPACTION_TIMEOUT_MS=30000
ROLEPLAY_UPSTREAM_HEADER_TIMEOUT_MS=90000
# Total generation budget includes all fallback/continuation legs; queue wait is separate.
ROLEPLAY_TURN_TIMEOUT_MS=600000
# Non-empty reasoning/content/terminal events count as progress; keepalive comments do not.
ROLEPLAY_STREAM_IDLE_TIMEOUT_MS=90000
ROLEPLAY_QUEUE_TIMEOUT_MS=120000
ROLEPLAY_MAX_PENDING_TURNS=4
# On roleplay:glm, ask standard GLM-5.3 Flash to signal an unavoidable refusal
# privately so the Worker can regenerate with the configured Uncensored Flash.
ROLEPLAY_REFUSAL_FALLBACK_ENABLED=true
# Max lets each selected model use its strongest supported reasoning profile;
# callers may still override reasoning_effort per turn.
ROLEPLAY_DEFAULT_REASONING_EFFORT=high
ROLEPLAY_STREAM_HEARTBEAT_MS=10000
# Keep generic Container-backed SSE routes alive during provider silence. Set 0 to disable.
SSE_STREAM_HEARTBEAT_MS=10000
# Unlimited SSE responses may stitch this many provider output-limit legs.
ROLEPLAY_MAX_AUTO_CONTINUATIONS=8
# A stopped response may use this many schema-repair legs for a required image prompt.
# Repairs that do not reduce the missing canonical field set are discarded immediately.
ROLEPLAY_MAX_OUTPUT_CONTRACT_REPAIRS=1
ROLEPLAY_SESSION_TTL_SECONDS=2592000

# PaLM API key
PALM_API_KEY=your-palm-api-key

# Nineteen AI API key
NINETEEN_API_KEY=your-nineteen-api-key

# Chutes AI API token
CHUTES_API_TOKEN=your-chutes-api-token

# Gemini API key
GEMINI_API_KEY=your-gemini-api-key

# Knowledge providers. Alexandria uses the same FIRECRAWL_API_KEY.
# Production: configure these as secrets on the private Knowledge Worker.
# Use the base key first, then numbered keys in numeric order on quota rejection.
# Blank and duplicate values are ignored; up to 32 distinct keys per provider.
FIRECRAWL_API_KEY=
FIRECRAWL_API_KEY_1=
CONTEXT7_API_KEY=
CONTEXT7_API_KEY_1=
CONTEXT7_API_KEY_2=
CONTEXT7_API_KEY_3=
CONTEXT7_API_KEY_4=
CONTEXT7_API_KEY_5=
CONTEXT7_API_KEY_6=
CONTEXT7_API_KEY_7=
EXA_API_KEY=
EXA_API_KEY_1=