All configuration is done through environment variables. Changes take effect only after restarting the affected service.
Copy .env.example from the repository root as a starting point — defaults are pre-configured for local development.
App
NEXT_PUBLIC_ENVIRONMENT
Runtime environment. Controls behavior such as logging verbosity and debug tooling.
Allowed values: dev, prod — Default: dev
URLs
NEXT_PUBLIC_BUILDER_URL
Public-facing URL of the Builder service. Used by the browser to make API calls and by other services to construct absolute URLs. Required.
NEXT_PUBLIC_PARTYSOCKET_URL
Public-facing URL of the PartySocket WebSocket server. Used by the browser to establish realtime connections. Required.
NEXT_PUBLIC_ASSET_URL
Base URL for serving user-uploaded files and generated assets from storage. Should point to the public bucket prefix.
Authentication
BETTER_AUTH_SECRET
Secret key used to sign and verify authentication tokens. Generate with:
Required. Keep this secret — rotating it invalidates all existing sessions.
BETTER_AUTH_URL
Base URL of the authentication server. Must match NEXT_PUBLIC_BUILDER_URL in most deployments. Required.
Database
DATABASE_URL
PostgreSQL connection URL. Required. The database must be reachable from all three services (Builder, Worker).
Redis
REDIS_URL
Primary Redis connection URL. Used as the default for all Redis roles (cache, queue, pub/sub) unless overridden by the variables below. Required.
REDIS_CACHE_URL
Dedicated Redis instance for caching. Falls back to REDIS_URL when not set.
REDIS_QUEUE_URL
Dedicated Redis instance for BullMQ job queues. Falls back to REDIS_URL when not set.
REDIS_SEQUENCE_URL
Dedicated Redis instance for sequence scheduling. Falls back to REDIS_URL when not set.
S3-compatible storage
Compatible with AWS S3, RustFS, MinIO, Cloudflare R2, and any S3-compatible provider.
S3_ENDPOINT
S3 API endpoint URL. Required for non-AWS providers.
S3_ACCESS_KEY_ID
S3 access key ID.
S3_SECRET_ACCESS_KEY
S3 secret access key.
S3_REGION
S3 bucket region.
S3_BUCKET
S3 bucket name.
Email
SMTP_SERVER
SMTP connection URL for outgoing email. Required. Use smtp:// for plain/STARTTLS and smtps:// for implicit TLS.
For local development, MailHog is included in the Docker Compose stack:
NEXT_PUBLIC_SMTP_FROM
Email address shown in the From field of outgoing messages. Required.
Realtime (PartySocket)
REALTIME_API_KEY
Shared secret used by the Builder and Worker to authenticate requests to the PartySocket service. Generate with:
Required. Must be the same value across all services.
Worker
SCHEDULER_BUCKET_RANGE
Hash bucket range this worker instance is responsible for in the sequence scheduler. For a single worker, use 0-255 (the full range). Split across replicas for horizontal scaling — e.g. 0-127 and 128-255 for two workers.
Default: 0-255
See the “channels” section of the documentation for the channel you want to configure, for details about how to set that up. 
