This document describes the environment configuration system in Trigger.dev, focusing on how environment variables are validated, organized, and used to initialize the platform's core systems. The configuration is centralized in env.server.ts and provides type-safe access to all runtime settings.
For information about deployment-specific configuration and registry settings, see Deployment Process. For details on how the RunEngine uses this configuration, see Run Engine Architecture.
Sources: apps/webapp/app/env.server.ts1-1000
The Trigger.dev environment configuration uses a schema-driven approach with Zod for validation, type coercion, and default values. All configuration is validated at application startup, ensuring invalid configurations fail fast.
Sources: apps/webapp/app/env.server.ts1-50 apps/webapp/app/v3/runEngine.server.ts1-219
The EnvironmentSchema in env.server.ts defines the complete configuration structure using Zod. This provides runtime validation, type inference, and transformation of environment variables.
Key Schema Patterns:
z.coerce.number() automatically converts them to numbersDEFAULT_ENV_EXECUTION_CONCURRENCY_LIMIT defaults to 100)Sources: apps/webapp/app/env.server.ts50-850
The database configuration supports read-write splitting with a primary database for writes and an optional read replica for queries.
| Variable | Type | Default | Description |
|---|---|---|---|
DATABASE_URL | string | required | Primary database connection URL (writes + reads) |
DIRECT_URL | string | required | Direct database URL for migrations |
DATABASE_READ_REPLICA_URL | string | optional | Read replica URL for read-only queries |
DATABASE_CONNECTION_LIMIT | number | 10 | Maximum connection pool size |
DATABASE_POOL_TIMEOUT | number | 60 | Connection pool timeout (seconds) |
DATABASE_CONNECTION_TIMEOUT | number | 20 | Individual connection timeout (seconds) |
Sources: apps/webapp/app/env.server.ts53-68
Base Redis settings that other Redis instances can inherit from:
| Variable | Type | Default | Description |
|---|---|---|---|
REDIS_HOST | string | optional | Default Redis host |
REDIS_PORT | number | optional | Default Redis port |
REDIS_USERNAME | string | optional | Default Redis username |
REDIS_PASSWORD | string | optional | Default Redis password |
REDIS_TLS_DISABLED | string | optional | Disable TLS for Redis |
REDIS_READER_HOST | string | optional | Read replica host |
REDIS_READER_PORT | number | optional | Read replica port |
Sources: apps/webapp/app/env.server.ts119-127
Trigger.dev uses multiple Redis instances for different purposes, each with dedicated configuration. This prevents contention and allows independent scaling.
Each specialized Redis instance follows the same configuration pattern with fallback to base Redis settings:
This pattern is repeated for:
RATE_LIMIT_REDIS_* - API rate limiting (lines 128-158)CACHE_REDIS_* - Application caching (lines 160-190)REALTIME_STREAMS_REDIS_* - Real-time stream data (lines 192-224)PUBSUB_REDIS_* - Event broadcasting (lines 232-262)ALERT_RATE_LIMITER_REDIS_* - Alert throttling (lines 453-485)RUN_ENGINE_WORKER_REDIS_* - RunEngine worker jobs (lines 650-681)RUN_ENGINE_RUN_QUEUE_REDIS_* - Run queue operations (lines 683-714)RUN_ENGINE_RUN_LOCK_REDIS_* - Distributed locking (lines 716-747)RUN_ENGINE_DEV_PRESENCE_REDIS_* - Development mode presence (lines 749-780)Sources: apps/webapp/app/env.server.ts128-780
The RunEngine is initialized with configuration from multiple categories of environment variables:
| Variable | Type | Default | Description |
|---|---|---|---|
RUN_ENGINE_WORKER_ENABLED | string | "1" | Enable/disable worker processing |
RUN_ENGINE_WORKER_COUNT | number | 4 | Number of worker processes |
RUN_ENGINE_TASKS_PER_WORKER | number | 10 | Concurrent tasks per worker |
RUN_ENGINE_WORKER_CONCURRENCY_LIMIT | number | 10 | Total concurrency limit |
RUN_ENGINE_WORKER_POLL_INTERVAL | number | 100 | Polling interval (ms) |
RUN_ENGINE_WORKER_IMMEDIATE_POLL_INTERVAL | number | 100 | Fast polling after work found (ms) |
RUN_ENGINE_WORKER_SHUTDOWN_TIMEOUT_MS | number | 60000 | Graceful shutdown timeout |
RUN_ENGINE_WORKER_LOG_LEVEL | enum | "info" | Worker logging level |
Sources: apps/webapp/app/env.server.ts576-820 apps/webapp/app/v3/runEngine.server.ts22-38
| Variable | Type | Default | Description |
|---|---|---|---|
RUN_ENGINE_RUN_QUEUE_SHARD_COUNT | number | 4 | Number of queue shards |
RUN_ENGINE_PARENT_QUEUE_LIMIT | number | 1000 | Parent queue size limit |
RUN_ENGINE_CONCURRENCY_LIMIT_BIAS | number | 0.75 | Queue selection bias for concurrency |
RUN_ENGINE_AVAILABLE_CAPACITY_BIAS | number | 0.3 | Queue selection bias for capacity |
RUN_ENGINE_QUEUE_AGE_RANDOMIZATION_BIAS | number | 0.25 | Randomization for queue age |
RUN_ENGINE_REUSE_SNAPSHOT_COUNT | number | 0 | Snapshot reuse optimization |
RUN_ENGINE_MAXIMUM_ENV_COUNT | number | optional | Max environments to consider |
RUN_ENGINE_DEQUEUE_BLOCKING_TIMEOUT_SECONDS | number | 10 | Blocking dequeue timeout |
RUN_ENGINE_MASTER_QUEUE_CONSUMERS_INTERVAL_MS | number | 1000 | Master queue polling interval |
Sources: apps/webapp/app/env.server.ts576-608 apps/webapp/app/v3/runEngine.server.ts45-76
The TTL system automatically expires runs that exceed their time-to-live:
| Variable | Type | Default | Description |
|---|---|---|---|
RUN_ENGINE_TTL_SYSTEM_DISABLED | boolean | false | Disable entire TTL system |
RUN_ENGINE_TTL_CONSUMERS_DISABLED | boolean | false | Disable polling loops only |
RUN_ENGINE_TTL_SYSTEM_SHARD_COUNT | number | optional | TTL shard count (defaults to queue shards) |
RUN_ENGINE_TTL_SYSTEM_POLL_INTERVAL_MS | number | 1000 | Polling frequency per shard |
RUN_ENGINE_TTL_SYSTEM_BATCH_SIZE | number | 100 | Max runs to expire per poll |
RUN_ENGINE_TTL_WORKER_CONCURRENCY | number | 1 | Worker concurrency for expiration |
RUN_ENGINE_TTL_WORKER_BATCH_MAX_SIZE | number | 50 | Max items per worker batch |
RUN_ENGINE_TTL_WORKER_BATCH_MAX_WAIT_MS | number | 5000 | Max batch accumulation time |
RUN_ENGINE_DEFAULT_MAX_TTL | string | optional | Default maximum TTL (e.g., "14d") |
Sources: apps/webapp/app/env.server.ts610-622 apps/webapp/app/v3/runEngine.server.ts83-92 internal-packages/run-engine/src/engine/types.ts66-87
Heartbeat timeouts control how long runs can remain in various states before being considered stalled:
| Variable | Type | Default | Description |
|---|---|---|---|
RUN_ENGINE_TIMEOUT_PENDING_EXECUTING | number | 60000 | Timeout for PENDING_EXECUTING state |
RUN_ENGINE_TIMEOUT_PENDING_CANCEL | number | 60000 | Timeout for PENDING_CANCEL state |
RUN_ENGINE_TIMEOUT_EXECUTING | number | 300000 | Timeout for EXECUTING state (5 min) |
RUN_ENGINE_TIMEOUT_EXECUTING_WITH_WAITPOINTS | number | 300000 | Timeout for EXECUTING_WITH_WAITPOINTS |
RUN_ENGINE_TIMEOUT_SUSPENDED | number | 600000 | Timeout for SUSPENDED state (10 min) |
Sources: apps/webapp/app/env.server.ts581-584 apps/webapp/app/v3/runEngine.server.ts118-124 internal-packages/run-engine/src/engine/types.ts154-160
The batch queue uses Deficit Round Robin (DRR) scheduling for fair batch processing:
| Variable | Type | Default | Description |
|---|---|---|---|
BATCH_QUEUE_WORKER_ENABLED | boolean | derived | Enable batch workers (follows main worker) |
BATCH_QUEUE_CONSUMER_COUNT | number | varies | Number of batch consumers |
BATCH_QUEUE_CONSUMER_INTERVAL_MS | number | 100 | Consumer polling interval |
BATCH_QUEUE_DRR_QUANTUM | number | varies | DRR quantum (items per round) |
BATCH_QUEUE_MAX_DEFICIT | number | varies | Maximum deficit accumulation |
BATCH_QUEUE_MASTER_QUEUE_LIMIT | number | optional | Master queue size limit |
BATCH_QUEUE_SHARD_COUNT | number | optional | Number of batch queue shards |
BATCH_QUEUE_WORKER_QUEUE_TIMEOUT_SECONDS | number | conditional | Worker queue blocking timeout |
BATCH_QUEUE_WORKER_QUEUE_MAX_DEPTH | number | optional | Worker queue depth limit |
BATCH_CONCURRENCY_LIMIT_DEFAULT | number | 5 | Default batch concurrency |
Sources: apps/webapp/app/env.server.ts563-564 apps/webapp/app/v3/runEngine.server.ts172-209 internal-packages/run-engine/src/engine/types.ts98-127
OpenTelemetry settings control observability for both development and production environments:
The system differentiates between development and production OpenTelemetry configurations:
Development Settings (DEV_OTEL_*):
Production Settings (PROD_OTEL_*):
Trigger OTEL Limits (TRIGGER_OTEL_*):
SPAN_ATTRIBUTE_COUNT_LIMIT: Default 1024LOG_ATTRIBUTE_COUNT_LIMIT: Default 1024SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT: Default 131072 (128KB)LOG_ATTRIBUTE_VALUE_LENGTH_LIMIT: Default 131072 (128KB)SPAN_EVENT_COUNT_LIMIT: Default 10LINK_COUNT_LIMIT: Default 2Internal OTEL (INTERNAL_OTEL_*):
Sources: apps/webapp/app/env.server.ts374-432
The configuration system uses discriminated unions for optional features, ensuring all related settings are present when enabled:
Sources: apps/webapp/app/env.server.ts6-48
The validated configuration flows from env.server.ts through to RunEngine and other subsystems:
Here's how configuration flows from environment variables to RunEngine initialization:
Sources: apps/webapp/app/v3/runEngine.server.ts15-218 internal-packages/run-engine/src/engine/index.ts113-439
The configuration system uses defaults strategically:
DATABASE_URL, ENCRYPTION_KEY)RUN_ENGINE_WORKER_COUNT: 4)GITHUB_APP_ENABLED: "0")The schema performs extensive validation:
| Validation Type | Example | Purpose |
|---|---|---|
| Format Validation | isValidDatabaseUrl() | Ensure connection strings are valid |
| Regex Validation | isValidRegex() for email patterns | Prevent runtime regex errors |
| Type Coercion | z.coerce.number() | Convert strings to numbers |
| Range Validation | z.coerce.number().int().positive() | Ensure values are in valid ranges |
| Length Validation | ENCRYPTION_KEY must be 32 bytes | Security requirements |
| Custom Refinement | Conditional validation based on other fields | Complex validation logic |
Sources: apps/webapp/app/env.server.ts53-79 apps/webapp/app/utils/boolEnv.ts apps/webapp/app/utils/db.ts
| Variable | Type | Default | Component |
|---|---|---|---|
DEFAULT_ENV_EXECUTION_CONCURRENCY_LIMIT | number | 100 | RunQueue |
DEFAULT_ENV_EXECUTION_CONCURRENCY_BURST_FACTOR | number | 1.0 | RunQueue |
DEFAULT_ORG_EXECUTION_CONCURRENCY_LIMIT | number | 300 | RunQueue |
DEFAULT_DEV_ENV_EXECUTION_ATTEMPTS | number | 1 | Development |
RUN_ENGINE_WORKER_CONCURRENCY_LIMIT | number | 10 | EngineWorker |
BATCH_CONCURRENCY_LIMIT_DEFAULT | number | 5 | BatchQueue |
MARQS_WORKER_CONCURRENCY_LIMIT | number | 50 | MARQS (legacy) |
| Variable | Type | Default | Component |
|---|---|---|---|
RUN_ENGINE_WORKER_POLL_INTERVAL | number | 100 | EngineWorker |
RUN_ENGINE_DEQUEUE_BLOCKING_TIMEOUT_SECONDS | number | 10 | RunQueue |
RUN_ENGINE_MASTER_QUEUE_CONSUMERS_INTERVAL_MS | number | 1000 | RunQueue |
RUN_ENGINE_TIMEOUT_EXECUTING | number | 300000 | RunEngine |
RUN_ENGINE_TIMEOUT_SUSPENDED | number | 600000 | RunEngine |
GRACEFUL_SHUTDOWN_TIMEOUT | number | 60000 | Server |
DEV_PRESENCE_TTL_MS | number | 5000 | Development |
| Variable | Type | Default | Description |
|---|---|---|---|
TASK_PAYLOAD_OFFLOAD_THRESHOLD | number | 524288 | 512KB - threshold for offloading to S3 |
TASK_PAYLOAD_MAXIMUM_SIZE | number | 3145728 | 3MB - maximum task payload size |
BATCH_TASK_PAYLOAD_MAXIMUM_SIZE | number | 1000000 | 1MB - maximum batch item payload |
TASK_RUN_METADATA_MAXIMUM_SIZE | number | 262144 | 256KB - maximum metadata size |
STREAMING_BATCH_MAX_ITEMS | number | 1000 | Maximum items in streaming batch |
STREAMING_BATCH_ITEM_MAXIMUM_SIZE | number | 3145728 | 3MB - streaming batch item size |
Sources: apps/webapp/app/env.server.ts264-563
| Purpose | Prefix | Key Variables | Fallback |
|---|---|---|---|
| Base | REDIS_ | HOST, PORT, USERNAME, PASSWORD, TLS_DISABLED | N/A |
| Rate Limiting | RATE_LIMIT_REDIS_ | All base vars + CLUSTER_MODE_ENABLED | Base Redis |
| Caching | CACHE_REDIS_ | All base vars + CLUSTER_MODE_ENABLED | Base Redis |
| Realtime Streams | REALTIME_STREAMS_REDIS_ | All base vars + CLUSTER_MODE_ENABLED | Base Redis |
| PubSub | PUBSUB_REDIS_ | All base vars + CLUSTER_MODE_ENABLED | Base Redis |
| Alert Rate Limiter | ALERT_RATE_LIMITER_REDIS_ | All base vars + CLUSTER_MODE_ENABLED | Base Redis |
| RunEngine Worker | RUN_ENGINE_WORKER_REDIS_ | All base vars | Base Redis |
| RunEngine Queue | RUN_ENGINE_RUN_QUEUE_REDIS_ | All base vars | Base Redis |
| RunEngine Lock | RUN_ENGINE_RUN_LOCK_REDIS_ | All base vars | Base Redis |
| Dev Presence | RUN_ENGINE_DEV_PRESENCE_REDIS_ | All base vars | Base Redis |
Sources: apps/webapp/app/env.server.ts119-780
This comprehensive configuration system ensures type-safe, validated, and well-organized environment configuration across all Trigger.dev subsystems.
Refresh this wiki