> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strait.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Variables
> Complete reference of environment variables used to configure Strait.
This page documents all environment variables available for configuring Strait.
Required fields: `DATABASE_URL`, `INTERNAL_SECRET`, `JWT_SIGNING_KEY`, `ENCRYPTION_KEY`, and `SECRET_ENCRYPTION_KEY`.
All environment variables are managed via [Doppler](https://doppler.com) (project: `strait`, configs: `dev` / `stg` / `prd`). Use `doppler run -- ` to inject secrets locally, or see the [Deployment Guide](/guides/deployment) for production setup.
## Core Configuration
| Variable | Type | Default | Description |
| :---------------------------- | :------ | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | String | (Required) | PostgreSQL connection string. |
| `REDIS_URL` | String | - | Redis connection string for pub/sub and CDC. |
| `MODE` | String | `all` | Operation mode: `all`, `api`, or `worker`. |
| `PORT` | Integer | `8080` | Port the HTTP server listens on. |
| `INTERNAL_SECRET` | String | (Required) | Secret used for internal authentication between components. |
| `JWT_SIGNING_KEY` | String | (Required) | Key used to sign JWT run tokens. Must be at least 32 characters. |
| `LOG_LEVEL` | String | `info` | Logging verbosity: `debug`, `info`, `warn`, `error`. |
| `SECRET_ENCRYPTION_KEY` | String | - | Key used to encrypt job secrets. Required when using secret injection. |
| `ENCRYPTION_KEY` | String | - | Key used for data encryption at rest. Should be unique per environment. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | String | - | OpenTelemetry collector endpoint for traces and logs. Also used by the slog-to-OTLP bridge. |
| `OTLP_METRIC_ENDPOINT` | String | - | Separate OTLP endpoint for metrics push (if different from trace endpoint). |
| `OTLP_METRIC_ENABLED` | Boolean | `false` | Enable OTLP metric push export. |
| `SENTRY_DSN` | String | - | Sentry DSN for error tracking. |
| `SENTRY_ENVIRONMENT` | String | - | Environment tag for Sentry and OTel resources (`dev`, `stg`, `prd`). Sets `deployment.environment` on all OTel metrics, traces, and logs. |
| `UPSTASH_REDIS_REST_URL` | String | - | Upstash Redis REST API URL. |
| `UPSTASH_REDIS_REST_TOKEN` | String | - | Upstash Redis REST API token. |
## Worker Configuration
| Variable | Type | Default | Description |
| :--------------------------- | :------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKER_CONCURRENCY` | Integer | `10` | Number of concurrent jobs a worker can execute. |
| `WEBHOOK_TIMEOUT` | Duration | `10s` | Timeout for webhook requests. |
| `WEBHOOK_IDLE_CONN_TIMEOUT` | Duration | `60s` | Idle connection timeout for webhook client. |
| `EXECUTOR_HTTP_TIMEOUT` | Duration | `5m` | Timeout for executor HTTP requests. |
| `EXECUTOR_IDLE_CONN_TIMEOUT` | Duration | `90s` | Idle connection timeout for executor client. |
| `WEBHOOK_MAX_ATTEMPTS` | Integer | `3` | Maximum number of attempts for webhook delivery. |
| `DEFAULT_JOB_MAX_ATTEMPTS` | Integer | `3` | Default maximum retry attempts for jobs. |
| `DEFAULT_JOB_TIMEOUT_SECS` | Integer | `300` | Default timeout for jobs in seconds. |
| `WORKER_QUEUE_SIZE` | Integer | `0` | Bounded task queue size for the worker pool. When the queue is full, task submission blocks until a slot opens, providing backpressure. `0` means unbounded. |
| `WEBHOOK_CONCURRENCY` | Integer | `50` | Maximum concurrent webhook deliveries. Increase for high-throughput webhook workloads. |
| `WEBHOOK_DISPATCH_TIMEOUT` | Duration | `15s` | Timeout for webhook dispatch requests. |
## Scheduler Configuration
| Variable | Type | Default | Description |
| :--------------------------- | :------- | :------ | :-------------------------------------------------------------------------------------------------------- |
| `HEARTBEAT_INTERVAL` | Duration | `10s` | Interval for worker heartbeats. |
| `REAPER_INTERVAL` | Duration | `30s` | Interval for the stale run reaper process. |
| `STALE_THRESHOLD` | Duration | `60s` | Threshold after which a run is considered stale. |
| `POLLER_INTERVAL` | Duration | `5s` | Interval for the job poller to check for new work. |
| `INDEX_MAINTENANCE_INTERVAL` | Duration | `24h` | Interval for partial index maintenance (`REINDEX INDEX CONCURRENTLY`). Set to `0` or negative to disable. |
| `REAPER_DELETE_BATCH_SIZE` | Integer | `100` | Number of records to delete in a single reaper batch. |
| `LOG_DRAIN_WORKER_INTERVAL` | Duration | `60s` | Interval for the log drain delivery worker. |
## Database Pool
| Variable | Type | Default | Description |
| :---------------------- | :------- | :------ | :------------------------------------------------------------------------------------------------------- |
| `DB_MAX_CONNS` | Integer | `25` | Maximum number of open connections to the database. |
| `DB_MIN_CONNS` | Integer | `5` | Minimum number of idle connections in the pool. |
| `DB_MAX_CONN_LIFETIME` | Duration | `30m` | Maximum amount of time a connection may be reused. |
| `DB_MAX_CONN_IDLE_TIME` | Duration | `5m` | Maximum amount of time a connection may be idle. |
| `DB_PGBOUNCER_MODE` | Boolean | `false` | Enable PgBouncer-compatible connection handling. Disables features incompatible with connection poolers. |
## Rate Limiting
| Variable | Type | Default | Description |
| :---------------------------- | :------- | :------ | :--------------------------------------------- |
| `RATE_LIMIT_REQUESTS` | Integer | `100` | Number of requests allowed per window. |
| `RATE_LIMIT_WINDOW` | Duration | `1m` | Time window for rate limiting. |
| `TRIGGER_RATE_LIMIT_REQUESTS` | Integer | `10` | Number of trigger requests allowed per window. |
| `TRIGGER_RATE_LIMIT_WINDOW` | Duration | `1m` | Time window for trigger rate limiting. |
## Request Configuration
| Variable | Type | Default | Description |
| :----------------------- | :------- | :------ | :-------------------------------------------------------- |
| `REQUEST_TIMEOUT` | Duration | `30s` | Timeout for incoming HTTP requests. |
| `MAX_REQUEST_BODY_SIZE` | Integer | `1MB` | Maximum size of the request body in bytes. |
| `MAX_BULK_TRIGGER_ITEMS` | Integer | `500` | Maximum number of items in a single bulk trigger request. |
## Sequin CDC
| Variable | Type | Default | Description |
| :--------------------- | :------ | :------ | :-------------------------------------------------- |
| `SEQUIN_BASE_URL` | String | - | Base URL for the Sequin CDC service. |
| `SEQUIN_CONSUMER_NAME` | String | - | Name of the Sequin consumer. |
| `SEQUIN_API_TOKEN` | String | - | API token for Sequin authentication. |
| `SEQUIN_BATCH_SIZE` | Integer | `10` | Number of events to fetch from Sequin in one batch. |
| `SEQUIN_WAIT_TIME_MS` | Integer | `5000` | Wait time in milliseconds for Sequin long polling. |
## CORS Configuration
| Variable | Type | Default | Description |
| :----------------------- | :---------- | :------ | :--------------------------------------------- |
| `CORS_ALLOWED_ORIGINS` | String List | `*` | Comma-separated list of allowed origins. |
| `CORS_ALLOW_CREDENTIALS` | Boolean | `false` | Whether to allow credentials in CORS requests. |
## OIDC Configuration
| Variable | Type | Default | Description |
| :-------------------- | :------ | :------ | :-------------------------------------------------- |
| `OIDC_ENABLED` | Boolean | `false` | Enable OpenID Connect authentication. |
| `OIDC_ISSUER` | String | - | OIDC token issuer URL. |
| `OIDC_AUDIENCE` | String | - | Expected OIDC audience claim. |
| `OIDC_PUBLIC_KEY_PEM` | String | - | PEM-encoded public key for OIDC token verification. |
## RBAC Configuration
| Variable | Type | Default | Description |
| :--------------------- | :------- | :------ | :--------------------------------- |
| `PERMISSION_CACHE_TTL` | Duration | `5m` | TTL for the RBAC permission cache. |
## CDC Configuration
| Variable | Type | Default | Description |
| :----------------- | :------ | :------ | :---------------------------------------------------- |
| `CDC_BATCH_SIZE` | Integer | `10` | Number of change events to process in a single batch. |
| `CDC_WAIT_TIME_MS` | Integer | `5000` | Wait time in milliseconds for CDC long polling. |
## Retention Configuration
| Variable | Type | Default | Description |
| :----------------------------- | :------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUN_RETENTION_SHORT` | Duration | `30d` | Short-term retention period for job runs. |
| `RUN_RETENTION_LONG` | Duration | `90d` | Long-term retention period for job runs. |
| `WORKFLOW_RUN_RETENTION_DAYS` | Integer | `30` | Number of days to retain workflow run data. |
| `WORKFLOW_RETENTION` | Duration | `30d` | Retention period for workflow definitions. |
| `EVENT_TRIGGER_RETENTION` | Duration | `168h` (7d) | Retention period for terminal event triggers. Terminal triggers older than this are purged by the reaper. Set to `0` to disable automatic cleanup. |
| `EVENT_TRIGGER_RETENTION_DAYS` | Integer | - | Legacy alternative: retention in days (e.g., `90`). Only used when `EVENT_TRIGGER_RETENTION` is not set. |
## Redis Sentinel
| Variable | Type | Default | Description |
| :---------------------- | :---------- | :------ | :------------------------------------------------ |
| `REDIS_SENTINEL_MASTER` | String | - | Name of the Redis Sentinel master. |
| `REDIS_SENTINEL_ADDRS` | String List | - | Comma-separated list of Redis Sentinel addresses. |
## Workflow Configuration
| Variable | Type | Default | Description |
| :---------------------------- | :------- | :--------- | :-------------------------------------------------------------------------------- |
| `MAX_WORKFLOW_NESTING_DEPTH` | Integer | `10` | Maximum allowed depth for nested workflows. |
| `WF_STALL_THRESHOLD` | Duration | `15m` | Max time without workflow progression before run is considered stalled by reaper. |
| `WF_STALL_ACTION` | String | `log_only` | Action when stalled run is detected: `log_only`, `reconcile`, or `fail_workflow`. |
| `WF_MAX_STEP_CAP` | Integer | `0` | Maximum number of steps allowed in a single workflow. `0` means unlimited. |
| `WF_STEP_CONCURRENCY_LIMIT` | Integer | `0` | Maximum concurrent step executions per workflow run. `0` means unlimited. |
| `DEPENDENCY_STATUS_CACHE_TTL` | Duration | `5s` | TTL for the job dependency status cache. |
## SSE Configuration
| Variable | Type | Default | Description |
| :----------------------- | :------- | :------ | :---------------------------------------------- |
| `SSE_KEEPALIVE_INTERVAL` | Duration | `15s` | Interval for sending keepalive events over SSE. |
## Worker Partitions
| Variable | Type | Default | Description |
| :------------------------- | :---------- | :------ | :-------------------------------------------- |
| `WORKER_PARTITIONS` | String List | - | List of partitions this worker should handle. |
| `WORKER_PARTITION_WEIGHTS` | String | - | Weights for the configured partitions. |
## Encryption
| Variable | Type | Default | Description |
| :------------------- | :---------- | :------ | :-------------------------------------------------- |
| `ENCRYPTION_KEY` | String | - | Primary key used for data encryption. |
| `ENCRYPTION_KEY_OLD` | String List | - | List of previous encryption keys used for rotation. |
## Managed Execution (Fly Machines)
| Variable | Type | Default | Description |
| :------------------------ | :------- | :------ | :-------------------------------------------------------------------------------------- |
| `COMPUTE_RUNTIME` | String | `none` | Container runtime for managed execution: `none`, `fly`, or `docker`. |
| `FLY_API_TOKEN` | String | - | Fly Machines API token. Required when `COMPUTE_RUNTIME=fly`. |
| `FLY_APP_NAME` | String | - | Fly app name for machine provisioning. Required when `COMPUTE_RUNTIME=fly`. |
| `FLY_REGION` | String | `iad` | Default Fly region for new machines. Overridden by job-level or run-level region hints. |
| `EXTERNAL_API_URL` | String | - | Public API URL injected into containers as `STRAIT_API_URL` for SDK callbacks. |
| `MAX_CONCURRENT_MACHINES` | Integer | `10` | Maximum number of parallel managed containers across all jobs. |
| `WARM_POOL_ENABLED` | Boolean | `false` | Enable warm machine pool for faster cold starts. |
| `WARM_POOL_MAX_PER_JOB` | Integer | `3` | Maximum warm machines per job/region combination. |
| `WARM_POOL_TTL` | Duration | `5m` | TTL for idle warm machines before they are destroyed. |
## Shutdown
| Variable | Type | Default | Description |
| :--------------------- | :------- | :------ | :------------------------------------------------------------------------- |
| `WORKER_DRAIN_TIMEOUT` | Duration | `30s` | Maximum time to wait for workers to finish in-flight jobs during shutdown. |
## Webhook Delivery
| Variable | Type | Default | Description |
| :-------------------------- | :------ | :------ | :----------------------------------------- |
| `WEBHOOK_MAX_PAYLOAD_BYTES` | Integer | `1MB` | Maximum size of webhook payloads in bytes. |
## Adaptive Concurrency
| Variable | Type | Default | Description |
| :------------------------- | :------ | :------ | :---------------------------------------------- |
| `ADAPTIVE_CONCURRENCY_MIN` | Integer | `5` | Minimum concurrency level for adaptive scaling. |
| `ADAPTIVE_CONCURRENCY_MAX` | Integer | `100` | Maximum concurrency level for adaptive scaling. |
## ClickHouse (Optional Analytics)
| Variable | Type | Default | Description |
| :-------------------------- | :------- | :------- | :------------------------------------------------------------------------------------------- |
| `CLICKHOUSE_ENABLED` | Boolean | `false` | Enable the ClickHouse client and create analytics tables on startup. |
| `CLICKHOUSE_URL` | String | - | ClickHouse native protocol URL (e.g., `clickhouse://localhost:9000`). Required when enabled. |
| `CLICKHOUSE_DATABASE` | String | `strait` | Target ClickHouse database name. |
| `CLICKHOUSE_BATCH_SIZE` | Integer | `1000` | Maximum records per batch insert. |
| `CLICKHOUSE_FLUSH_INTERVAL` | Duration | `5s` | Maximum time between exporter flushes. |
| `CLICKHOUSE_EXPORT_ENABLED` | Boolean | `false` | Enable the async exporter that sends run analytics to ClickHouse on run completion. |