.env.example

# narn server configuration. Copy to `.env` and adjust.
#
# Storage is Postgres-everywhere: the server REQUIRES a Postgres connection and
# throws on boot if DATABASE_URL is unset. (The old filesystem-JSON project store
# is gone.) The bundled docker-compose.yml brings its own Postgres and sets
# DATABASE_URL for you, but that Postgres publishes no host port, so it is not
# reachable from a bare-metal `pnpm dev` run. The value below is for `pnpm dev`
# against a Postgres you run yourself (see CONTRIBUTING.md).

# ── Required ─────────────────────────────────────────────────────────────────
# Postgres connection string.
DATABASE_URL=postgres://translator:translator@localhost:5432/translator

# Elevated (e.g. superuser) connection string used ONLY to apply schema migrations.
# Unset → migrations run on the normal runtime pool.
# MIGRATION_DATABASE_URL=postgres://migrator:migrator@localhost:5432/translator

# ── Server ───────────────────────────────────────────────────────────────────
# Port to listen on (default: 3001).
# PORT=3001

# Interface to bind. Default 127.0.0.1 (loopback only). Set 0.0.0.0 ONLY when you
# intentionally want LAN/container-network access (the Docker image sets this).
# HOST=127.0.0.1

# production | development. Affects logging and secure-cookie defaults.
# NODE_ENV=development

# Absolute path to the built SPA the server serves. Set in the Docker image; for
# bare-metal dev the frontend is served by Vite on :5173 instead, so leave unset.
# FRONTEND_DIST=/app/frontend-dist

# ── Network / browser-security guards ────────────────────────────────────────
# Extra hostname permitted by the anti-DNS-rebinding Host-header guard. Only needed
# when HOST is a non-loopback interface.
# ALLOWED_HOST=my-dev-box.local

# Comma-separated origins allowed for CORS (default: http://localhost:5173).
# CORS_ORIGIN=http://localhost:5173

# Extra trusted origin for the origin/referer CSRF guard (falls back to ALLOWED_HOST).
# CSRF_TRUSTED_ORIGIN=https://app.example.com

# Extra space-separated origins appended to the CSP `connect-src` directive — e.g.
# a custom LLM endpoint the SPA must reach directly from the browser.
# CSP_CONNECT_SRC=https://llm.example.com

# Send an HSTS header (only meaningful when served over TLS). Set to 1 to enable.
# ENABLE_HSTS=1

# SSRF-guard escape hatch (operator-only, default off). Set to true ONLY if your LLM
# endpoint is legitimately on a link-local/internal/metadata host on a trusted network.
# ALLOW_INTERNAL_LLM_HOSTS=true

# ── Behind a reverse proxy (optional) ────────────────────────────────────────
# Trust X-Forwarded-* headers and mark cookies secure (implied when NODE_ENV=production).
# TRUST_PROXY=1
# Comma-separated proxy peer IPs/CIDRs trusted for client-IP extraction.
# TRUSTED_PROXY_IPS=10.0.0.0/8
# Trust the CDN/reverse proxy's client-IP header. Requires TRUSTED_PROXY_IPS —
# the header is honored only from a matching proxy peer. Set to 1.
# TRUST_PROXY_CLIENT_IP=1
# Header carrying the true client IP; defaults to cf-connecting-ip.
# PROXY_CLIENT_IP_HEADER=cf-connecting-ip

# ── Filesystem (vault, backups, audit logs) ──────────────────────────────────
# Local (non-cloud) encrypted credential vault file. Module API keys live here,
# AES-256-GCM-encrypted with your vault password.
# VAULT_FILE=./.translator-vault.json

# Filesystem root for per-project backups / auto-snapshots (default: ./projects).
# Project DATA itself lives in Postgres now — this is only the backup/snapshot tree.
# PROJECTS_ROOT=./projects

# Directory for audit logs (default: ./logs).
# AUDIT_LOG_DIR=./logs

# How many days of audit logs to keep (default: 7). A non-numeric or <=0 value falls
# back to the default.
# AUDIT_LOG_RETENTION_DAYS=7

# Base directory for the provider model-list cache; a `.cache` subdirectory is created
# inside it. Unset → the server's working directory.
# MODELS_CACHE_DIR=/var/cache/narn

# ── Limits & logging ─────────────────────────────────────────────────────────
# Max concurrent background runs (translation/judge/etc.) per tenant (example value).
# MAX_CONCURRENT_RUNS_PER_TENANT=3

# Max string entries one tenant may store across all their projects. A CSV import that
# would take them past it is refused, before anything is written, with a message naming
# the limit. Unset = unbounded (example value).
# MAX_STRING_ENTRIES_PER_TENANT=250000

# How many backups/auto-snapshots to keep per project. Malformed values are rejected
# at the call site.
# MAX_BACKUPS_PER_PROJECT=10

# How many translation jobs the engine's queue runs at once (default: 3).
# TRANSLATION_CONCURRENCY=3

# Governed concurrency ceiling for Freeway (free-tier AI routing) dispatch, separate
# from TRANSLATION_CONCURRENCY above (default: 32).
# FREEWAY_MAX_CONCURRENCY=32

# Fraction (0-1) of each free-tier bucket's declared per-minute rpm/tpm the rate
# governor paces dispatch against — kept below 1 so retries/reroutes have slack
# before a bucket's real ceiling (default: 0.7).
# FREEWAY_TARGET_UTILIZATION=0.7

# How many minutes of a bucket's per-minute allowance the run planner may commit
# in one plan — the planner sees a whole run at once but would otherwise spend
# minute headroom as though every request fired in the same instant (default: 10).
# PLAN_HORIZON_MINUTES=10

# Postgres connection-pool size. Kept above FREEWAY_MAX_CONCURRENCY + the ordinary
# concurrency ceiling so the pool is never the bottleneck (default: 48).
# PG_POOL_MAX=48

# Set to `json` for structured logs (default: human-readable).
# LOG_FORMAT=json

# Enable verbose debug logging.
# DEBUG=*

# TEST/dev ONLY — disable rate limiting and expose a lockout-reset seam. NEVER in
# production.
# RATE_LIMIT_DISABLED=1

# Contact address shown in the UI (account page, error boundary, unknown-view
# message). Unset → those contact links are hidden entirely.
# SUPPORT_EMAIL=

# ── Restart notices / ops (optional) ─────────────────────────────────────────
# Enable the restart-notice banners in the UI. On when set to 1|true|yes|on.
# RESTART_BANNERS_ENABLED=1

# The "recently restarted" window, in milliseconds (default: 300000). A non-numeric
# or <=0 value falls back to the default.
# RESTART_RECENTLY_WINDOW_MS=300000

# Free-text label for this deployment, shown as an environment ribbon in the UI and
# used to mark the instance as a non-production slot. Blank/unset → no ribbon.
# SLOT_LABEL=staging

# Shared secret for the operator restart-notice endpoints, sent as an X-Restart-Token
# header and compared in constant time. Unset/blank → those endpoints reject every
# request, which is the default.
# RESTART_ADMIN_TOKEN=