WordloopConfiguration
Every environment variable, config key, and feature flag, organised by service.
Configuration
Every service in the Wordloop platform loads its configuration from environment variables, following the Twelve-Factor App config principle. This page is the canonical catalogue of those variables — what they do, what their defaults are, and which service owns them.
Local defaults are generated by ./dev setup env. The variables listed here are the full contract; your local .env files typically override only the subset you need.
Common variables
Variables consumed by multiple services.
| Variable | Service(s) | Default (local) | Purpose |
|---|---|---|---|
APP_ENV | all | development | development, test, staging, production. Controls auth mode, logging verbosity, and feature defaults. |
DATABASE_URL | core | derived | Postgres connection string. |
PUBSUB_EMULATOR_HOST | core, ml | localhost:8085 | Local Pub/Sub emulator. Unset in production. |
OTEL_EXPORTER_OTLP_ENDPOINT | all | http://localhost:4318 | Collector endpoint for traces, metrics, and logs. |
LOG_LEVEL | all | info | debug, info, warn, error. |
wordloop-core
| Variable | Default | Purpose |
|---|---|---|
CORE_PORT | 4002 | HTTP + WebSocket port. |
CLERK_SECRET_KEY | — | Backend Clerk key for JWT verification. |
CLERK_PUBLISHABLE_KEY | — | Frontend-shared key; surfaced for debug. |
STORAGE_BUCKET | wordloop-local-audio | GCS bucket for audio artefacts. |
wordloop-ml
| Variable | Default | Purpose |
|---|---|---|
ML_PORT | 4003 | FastAPI port. |
MODEL_PROVIDER | anthropic | Chooses which model adapter to load. |
ANTHROPIC_API_KEY | — | Set when MODEL_PROVIDER=anthropic. |
OPENAI_API_KEY | — | Set when MODEL_PROVIDER=openai. |
ML_CACHE_TTL_SECONDS | 3600 | Cache lifetime for deterministic model calls. |
wordloop-app
| Variable | Default | Purpose |
|---|---|---|
NEXT_PUBLIC_CORE_URL | http://localhost:4002 | URL the browser uses to reach Core. |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | — | Clerk frontend key. |
APP_PORT | 4001 | Next.js port. |
Feature flags
Feature flags are served dynamically — they are not environment variables. See the flag dashboard for the current state and owners. Progressive-delivery principles (Progressive Delivery) govern how flags are created, rolled, and retired.
Further reading
- Quickstart — bootstrapping local
.envfiles. - Security — the rules around secret handling.
- Twelve-Factor App — the philosophy behind environment-based config.