# Configuration Options

The Hatchet server and engine can be configured via environment variables using several prefixes. This document contains a comprehensive list of all 197+ available options organized by component.

## Environment Variable Prefixes

Hatchet uses the following environment variable prefixes:

- **`SERVER_`** (172 variables) - Main server configuration including runtime, authentication, encryption, monitoring, and integrations
- **`DATABASE_`** (19 variables) - PostgreSQL database connection and configuration
- **`READ_REPLICA_`** (4 variables) - Read replica database configuration
- **`ADMIN_`** (3 variables) - Administrator user setup for initial seeding
- **`DEFAULT_`** (3 variables) - Default tenant configuration
- **`SCHEDULER_`** (1 variable) - Scheduler-specific rate limiting
- **`SEED_`** (1 variable) - Development environment seeding
- **`CACHE_`** (1 variable) - Cache duration settings

_Note: This documentation excludes `HATCHET*CLIENT*_` variables which are specific to Go SDK client configuration.\*

## Required Environment Variables

The following variables are **absolutely required** for Hatchet to start successfully:

### Encryption Keys (Required - Choose One Strategy)

**Option A: Local Encryption Keys**

```bash
SERVER_ENCRYPTION_MASTER_KEYSET="<base64-encoded-keyset>"
SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET="<base64-encoded-jwt-public>"
SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET="<base64-encoded-jwt-private>"
```

**Option B: File-based Keys**

```bash
SERVER_ENCRYPTION_MASTER_KEYSET_FILE="/path/to/master.keyset"
SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET_FILE="/path/to/jwt-public.keyset"
SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET_FILE="/path/to/jwt-private.keyset"
```

**Option C: Google Cloud KMS**

```bash
SERVER_ENCRYPTION_CLOUDKMS_ENABLED=true
SERVER_ENCRYPTION_CLOUDKMS_KEY_URI="gcp-kms://your-key-uri"
SERVER_ENCRYPTION_CLOUDKMS_CREDENTIALS_JSON="<credentials-json>"
```

### Authentication Secrets (Required)

```bash
SERVER_AUTH_COOKIE_SECRETS="<secret1> <secret2>"
```

### Database Connection (Required)

**Option A: Connection String**

```bash
DATABASE_URL="postgresql://user:password@host:port/dbname"
```

**Option B: Individual Parameters** (uses defaults if not specified)

```bash
DATABASE_POSTGRES_HOST=your-postgres-host
DATABASE_POSTGRES_PASSWORD=your-secure-password
```

## Minimal Configuration Example

> **Warning:** This example is for local development when Hatchet connects to PostgreSQL
>   running on the same host. For Docker Compose deployments, use your database
>   service name, such as `postgres`, instead of `127.0.0.1`. See the [Docker
>   Compose deployment guide](/self-hosting/docker-compose).

```bash
# Database
DATABASE_URL='postgresql://hatchet:hatchet@127.0.0.1:5431/hatchet'

# Encryption (using key files - recommended for development)
SERVER_ENCRYPTION_MASTER_KEYSET_FILE=./keys/master.key
SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET_FILE=./keys/private_ec256.key
SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET_FILE=./keys/public_ec256.key

# Authentication
SERVER_AUTH_COOKIE_SECRETS="your-secret-key-1 your-secret-key-2"
SERVER_AUTH_SET_EMAIL_VERIFIED=true

# Basic server config
SERVER_PORT=8080
SERVER_URL=http://localhost:8080

# Development settings (optional but recommended)
SERVER_GRPC_INSECURE=true
SERVER_INTERNAL_CLIENT_BASE_STRATEGY=none
SERVER_LOGGER_LEVEL=error
SERVER_LOGGER_FORMAT=console
DATABASE_LOGGER_LEVEL=error
DATABASE_LOGGER_FORMAT=console
```

Generate encryption keys with:

```bash
go run ./cmd/hatchet-admin keyset create-local-keys --key-dir ./keys
```

## Runtime Configuration

Variables marked with ⚠️ are conditionally required when specific features are enabled.

Variable, Description, Default Value

`SERVER_PORT`, Port for the core server, `8080`
`SERVER_URL`, Full server URL, including protocol, `http://localhost:8080`
`SERVER_GRPC_PORT`, Port for the GRPC service, `7070`
`SERVER_GRPC_BIND_ADDRESS`, GRPC server bind address, `127.0.0.1`
`SERVER_GRPC_BROADCAST_ADDRESS`, GRPC server broadcast address, `127.0.0.1:7070`
`SERVER_GRPC_INSECURE`, Controls if the GRPC server is insecure, `false`
`SERVER_ENFORCE_LIMITS`, Enforce tenant limits, `false`
`SERVER_ALLOW_SIGNUP`, Allow new tenant signups, `true`
`SERVER_ALLOW_INVITES`, Allow new invites, `true`
`SERVER_ALLOW_CREATE_TENANT`, Allow tenant creation, `true`
`SERVER_ALLOW_CHANGE_PASSWORD`, Allow password changes, `true`
`SERVER_HEALTHCHECK`, Enable healthcheck endpoint, `true`
`SERVER_HEALTHCHECK_PORT`, Healthcheck port, `8733`
`SERVER_GRPC_MAX_MSG_SIZE`, gRPC max message size, `4194304`
`SERVER_GRPC_RATE_LIMIT`, gRPC rate limit, `1000`
`SCHEDULER_CONCURRENCY_RATE_LIMIT`, Scheduler concurrency rate limit, `20`
`SCHEDULER_CONCURRENCY_POLLING_MIN_INTERVAL`, Minimum concurrency polling interval, `500ms`
`SCHEDULER_CONCURRENCY_POLLING_MAX_INTERVAL`, Maximum concurrency polling interval, `5s`
`SCHEDULER_ADVISORY_LOCK_TIMEOUT`, Timeout for in-memory advisory lock, `5s`
`SERVER_SERVICES`, Services to run, `["all"]`
`SERVER_PAUSED_CONTROLLERS`, Paused controllers
`SERVER_ENABLE_DATA_RETENTION`, Enable data retention, `true`
`SERVER_ENABLE_WORKER_RETENTION`, Enable worker retention, `false`
`SERVER_MAX_PENDING_INVITES`, Max pending invites, `100`
`SERVER_DISABLE_TENANT_PUBS`, Disable tenant pubsub
`SERVER_MAX_INTERNAL_RETRY_COUNT`, Max internal retry count, `10`
`SERVER_PREVENT_TENANT_VERSION_UPGRADE`, Prevent tenant version upgrades, `false`
`SERVER_DEFAULT_ENGINE_VERSION`, Default engine version, `V1`
`SERVER_REPLAY_ENABLED`, Enable task replay, `true`

## Database Configuration

> **Info:** In Docker Compose deployments, use the database service name in `DATABASE_URL`
>   rather than `127.0.0.1`. Inside a container, `127.0.0.1` refers to the
>   container itself. The localhost defaults shown in this section are intended
>   for local development on the same host.

Variable, Description, Default Value

`DATABASE_URL`, PostgreSQL connection string constructed from database settings if unset
`DATABASE_POSTGRES_HOST`, PostgreSQL host, `127.0.0.1`
`DATABASE_POSTGRES_PORT`, PostgreSQL port, `5431`
`DATABASE_POSTGRES_USERNAME`, PostgreSQL username, `hatchet`
`DATABASE_POSTGRES_PASSWORD`, PostgreSQL password, `hatchet`
`DATABASE_POSTGRES_DB_NAME`, PostgreSQL database name, `hatchet`
`DATABASE_POSTGRES_SSL_MODE`, PostgreSQL SSL mode, `disable`
`DATABASE_MAX_CONNS`, Max database connections, `50`
`DATABASE_MIN_CONNS`, Min database connections, `10`
`DATABASE_MAX_QUEUE_CONNS`, Max queue connections, `50`
`DATABASE_MIN_QUEUE_CONNS`, Min queue connections, `10`
`DATABASE_MAX_CONN_LIFETIME`, Max lifetime of a connection, `15m`
`DATABASE_MAX_CONN_IDLE_TIME`, Max time a connection can be idle before being closed, `1m`
`DATABASE_LOG_QUERIES`, Log database queries, `false`
`DATABASE_PGBOUNCER_ENABLED`, Enable pgbouncer support; requires `DATABASE_DIRECT_URL` to be set, `false`
`DATABASE_DIRECT_URL`, Direct PostgreSQL connection string bypassing pgbouncer for DDL operations
`DATABASE_DIRECT_MAX_CONNS`, Max connections for the direct (non-pgbouncer) pool, `2`
`DATABASE_DIRECT_MIN_CONNS`, Min connections for the direct (non-pgbouncer) pool, `1`
`CACHE_DURATION`, Cache duration, `5s`
`ADMIN_EMAIL`, Admin email for seeding, `admin@example.com`
`ADMIN_PASSWORD`, Admin password for seeding, `Admin123!!`
`ADMIN_NAME`, Admin name for seeding, `Admin`
`DEFAULT_TENANT_NAME`, Default tenant name, `Default`
`DEFAULT_TENANT_SLUG`, Default tenant slug, `default`
`DEFAULT_TENANT_ID`, Default tenant ID
`SEED_DEVELOPMENT`, Development seeding flag
`READ_REPLICA_ENABLED`, Enable read replica, `false`
`READ_REPLICA_DATABASE_URL`, Read replica database URL
`READ_REPLICA_MAX_CONNS`, Read replica max connections, `50`
`READ_REPLICA_MIN_CONNS`, Read replica min connections, `10`
`DATABASE_LOGGER_LEVEL`, Database logger level
`DATABASE_LOGGER_FORMAT`, Database logger format

## Security Check Configuration

Variable, Description, Default Value

`SERVER_SECURITY_CHECK_ENABLED`, Enable security check, `true`
`SERVER_SECURITY_CHECK_ENDPOINT`, Security check endpoint, `https://security.hatchet.run`

## Limit Configuration

Variable, Description, Default Value

`SERVER_LIMITS_DEFAULT_TENANT_RETENTION_PERIOD`, Default tenant retention period, `720h`
`SERVER_LIMITS_DEFAULT_WORKER_LIMIT`, Default worker limit, `4`
`SERVER_LIMITS_DEFAULT_WORKER_ALARM_LIMIT`, Default worker alarm limit, `2`
`SERVER_LIMITS_DEFAULT_EVENT_LIMIT`, Default event limit, `1000`
`SERVER_LIMITS_DEFAULT_EVENT_ALARM_LIMIT`, Default event alarm limit, `750`
`SERVER_LIMITS_DEFAULT_EVENT_WINDOW`, Default event window, `24h`
`SERVER_LIMITS_DEFAULT_CRON_LIMIT`, Default cron limit, `5`
`SERVER_LIMITS_DEFAULT_CRON_ALARM_LIMIT`, Default cron alarm limit, `2`
`SERVER_LIMITS_DEFAULT_SCHEDULE_LIMIT`, Default schedule limit, `1000`
`SERVER_LIMITS_DEFAULT_SCHEDULE_ALARM_LIMIT`, Default schedule alarm limit, `750`
`SERVER_LIMITS_DEFAULT_TASK_RUN_LIMIT`, Default task run limit, `2000`
`SERVER_LIMITS_DEFAULT_TASK_RUN_ALARM_LIMIT`, Default task run alarm limit, `1500`
`SERVER_LIMITS_DEFAULT_TASK_RUN_WINDOW`, Default task run window, `24h`
`SERVER_LIMITS_DEFAULT_WORKER_SLOT_LIMIT`, Default worker slot limit, `4000`
`SERVER_LIMITS_DEFAULT_WORKER_SLOT_ALARM_LIMIT`, Default worker slot alarm limit, `3000`

## Alerting Configuration

Variable, Description, Default Value

`SERVER_ALERTING_SENTRY_ENABLED`, Enable Sentry for alerting
`SERVER_ALERTING_SENTRY_DSN`, Sentry DSN
`SERVER_ALERTING_SENTRY_ENVIRONMENT`, Sentry environment, `development`
`SERVER_ALERTING_SENTRY_SAMPLE_RATE`, Sentry sample rate, `1.0`
`SERVER_ANALYTICS_POSTHOG_ENABLED`, Enable PostHog analytics
`SERVER_ANALYTICS_POSTHOG_API_KEY`, PostHog API key
`SERVER_ANALYTICS_POSTHOG_ENDPOINT`, PostHog endpoint
`SERVER_ANALYTICS_POSTHOG_FE_API_HOST`, PostHog frontend API host
`SERVER_ANALYTICS_POSTHOG_FE_API_KEY`, PostHog frontend API key
`SERVER_PYLON_ENABLED`, Enable Pylon
`SERVER_PYLON_APP_ID` ⚠️, Pylon app ID (required if Pylon enabled)
`SERVER_PYLON_SECRET`, Pylon secret

## Encryption Configuration

Variable, Description, Default Value

`SERVER_ENCRYPTION_MASTER_KEYSET`, Raw master keyset, base64-encoded JSON string
`SERVER_ENCRYPTION_MASTER_KEYSET_FILE`, Path to the master keyset file
`SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET`, Public JWT keyset, base64-encoded JSON string
`SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET_FILE`, Path to the public JWT keyset file
`SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET`, Private JWT keyset, base64-encoded JSON string
`SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET_FILE`, Path to the private JWT keyset file
`SERVER_ENCRYPTION_CLOUDKMS_ENABLED`, Whether Google Cloud KMS is enabled, `false`
`SERVER_ENCRYPTION_CLOUDKMS_KEY_URI`, URI of the key in Google Cloud KMS
`SERVER_ENCRYPTION_CLOUDKMS_CREDENTIALS_JSON`, JSON credentials for Google Cloud KMS

## Authentication Configuration

Variable, Description, Default Value

`SERVER_AUTH_RESTRICTED_EMAIL_DOMAINS`, Restricted email domains
`SERVER_AUTH_BASIC_AUTH_ENABLED`, Whether basic auth is enabled, `true`
`SERVER_AUTH_SET_EMAIL_VERIFIED`, Whether the user's email is set to verified automatically, `false`
`SERVER_AUTH_COOKIE_NAME`, Name of the cookie, `hatchet`
`SERVER_AUTH_COOKIE_DOMAIN`, Domain for the cookie
`SERVER_AUTH_COOKIE_SECRETS`, Cookie secrets
`SERVER_AUTH_COOKIE_INSECURE`, Whether the cookie is insecure, `false`
`SERVER_AUTH_GOOGLE_ENABLED`, Whether Google auth is enabled, `false`
`SERVER_AUTH_GOOGLE_CLIENT_ID` ⚠️, Google auth client ID (required if Google auth enabled)
`SERVER_AUTH_GOOGLE_CLIENT_SECRET` ⚠️, Google auth client secret (required if Google auth enabled)
`SERVER_AUTH_GOOGLE_SCOPES`, Google auth scopes, `["openid", "profile", "email"]`
`SERVER_AUTH_GITHUB_ENABLED`, Whether GitHub auth is enabled, `false`
`SERVER_AUTH_GITHUB_CLIENT_ID` ⚠️, GitHub auth client ID (required if GitHub auth enabled)
`SERVER_AUTH_GITHUB_CLIENT_SECRET` ⚠️, GitHub auth client secret (required if GitHub auth enabled)
`SERVER_AUTH_GITHUB_SCOPES`, GitHub auth scopes, `["read:user", "user:email"]`

## Task Queue Configuration

Variable, Description, Default Value

`SERVER_MSGQUEUE_KIND`, Message queue kind, `rabbitmq`
`SERVER_MSGQUEUE_RABBITMQ_URL`, RabbitMQ URL
`SERVER_MSGQUEUE_RABBITMQ_QOS`, RabbitMQ QoS, `100`
`SERVER_REQUEUE_LIMIT`, Requeue limit, `100`
`SERVER_SINGLE_QUEUE_LIMIT`, Single queue limit, `100`
`SERVER_UPDATE_HASH_FACTOR`, Update hash factor, `100`
`SERVER_UPDATE_CONCURRENT_FACTOR`, Update concurrent factor, `10`

## TLS Configuration

Variable, Description, Default Value

`SERVER_TLS_STRATEGY`, TLS strategy
`SERVER_TLS_CERT`, TLS certificate
`SERVER_TLS_CERT_FILE`, Path to the TLS certificate file
`SERVER_TLS_KEY`, TLS key
`SERVER_TLS_KEY_FILE`, Path to the TLS key file
`SERVER_TLS_ROOT_CA`, TLS root CA
`SERVER_TLS_ROOT_CA_FILE`, Path to the TLS root CA file
`SERVER_TLS_SERVER_NAME`, TLS server name
`SERVER_INTERNAL_CLIENT_BASE_STRATEGY`, Internal client TLS strategy
`SERVER_INTERNAL_CLIENT_BASE_INHERIT_BASE`, Inherit base TLS config, `true`
`SERVER_INTERNAL_CLIENT_TLS_BASE_CERT`, Internal client TLS cert
`SERVER_INTERNAL_CLIENT_TLS_BASE_CERT_FILE`, Internal client TLS cert file
`SERVER_INTERNAL_CLIENT_TLS_BASE_KEY`, Internal client TLS key
`SERVER_INTERNAL_CLIENT_TLS_BASE_KEY_FILE`, Internal client TLS key file
`SERVER_INTERNAL_CLIENT_TLS_BASE_ROOT_CA`, Internal client TLS root CA
`SERVER_INTERNAL_CLIENT_TLS_BASE_ROOT_CA_FILE`, Internal client TLS root CA file
`SERVER_INTERNAL_CLIENT_TLS_SERVER_NAME`, Internal client TLS server name
`SERVER_INTERNAL_CLIENT_INTERNAL_GRPC_BROADCAST_ADDRESS`, Internal gRPC broadcast address

## Logging Configuration

Variable, Description, Default Value

`SERVER_LOGGER_LEVEL`, Logger level
`SERVER_LOGGER_FORMAT`, Logger format
`SERVER_LOG_INGESTION_ENABLED`, Enable log ingestion, `true`
`SERVER_ADDITIONAL_LOGGERS_QUEUE_LEVEL`, Queue logger level
`SERVER_ADDITIONAL_LOGGERS_QUEUE_FORMAT`, Queue logger format
`SERVER_ADDITIONAL_LOGGERS_PGXSTATS_LEVEL`, PGX stats logger level
`SERVER_ADDITIONAL_LOGGERS_PGXSTATS_FORMAT`, PGX stats logger format

## OpenTelemetry Configuration

Variable, Description, Default Value

`SERVER_OTEL_SERVICE_NAME`, Service name for OpenTelemetry
`SERVER_OTEL_COLLECTOR_URL`, Collector URL for OpenTelemetry
`SERVER_OTEL_INSECURE`, Whether to use an insecure connection to the collector URL
`SERVER_OTEL_TRACE_ID_RATIO`, OpenTelemetry trace ID ratio
`SERVER_OTEL_COLLECTOR_AUTH`, OpenTelemetry Collector Authorization header value
`SERVER_OTEL_METRICS_ENABLED`, Enable OpenTelemetry metrics collection, `false`
`SERVER_PROMETHEUS_ENABLED`, Enable Prometheus, `false`
`SERVER_PROMETHEUS_ADDRESS`, Prometheus address, `:9090`
`SERVER_PROMETHEUS_PATH`, Prometheus metrics path, `/metrics`
`SERVER_PROMETHEUS_SERVER_URL`, Prometheus server URL
`SERVER_PROMETHEUS_SERVER_USERNAME`, Prometheus server username
`SERVER_PROMETHEUS_SERVER_PASSWORD`, Prometheus server password

## Tenant Alerting Configuration

Variable, Description, Default Value

`SERVER_TENANT_ALERTING_SLACK_ENABLED`, Enable Slack for tenant alerting
`SERVER_TENANT_ALERTING_SLACK_CLIENT_ID`, Slack client ID
`SERVER_TENANT_ALERTING_SLACK_CLIENT_SECRET`, Slack client secret
`SERVER_TENANT_ALERTING_SLACK_SCOPES`, Slack scopes, `["incoming-webhook"]`
`SERVER_EMAIL_KIND`, Email integration kind, `postmark`
`SERVER_EMAIL_POSTMARK_ENABLED`, Enable Postmark
`SERVER_EMAIL_POSTMARK_SERVER_KEY`, Postmark server key
`SERVER_EMAIL_POSTMARK_FROM_EMAIL`, Postmark from email
`SERVER_EMAIL_POSTMARK_FROM_NAME`, Postmark from name, `Hatchet Support`
`SERVER_EMAIL_POSTMARK_SUPPORT_EMAIL`, Postmark support email
`SERVER_EMAIL_SMTP_ENABLED`, Enable SMTP
`SERVER_EMAIL_SMTP_SERVER_ADDR`, SMTP server address
`SERVER_EMAIL_SMTP_FROM_EMAIL`, SMTP from email
`SERVER_EMAIL_SMTP_FROM_NAME`, SMTP from name, `Hatchet Support`
`SERVER_EMAIL_SMTP_SUPPORT_EMAIL`, SMTP support email
`SERVER_EMAIL_SMTP_AUTH_USERNAME`, SMTP authentication username
`SERVER_EMAIL_SMTP_AUTH_PASSWORD`, SMTP authentication password
`SERVER_MONITORING_ENABLED`, Enable monitoring, `true`
`SERVER_MONITORING_PERMITTED_TENANTS`, Permitted tenants for monitoring
`SERVER_MONITORING_PROBE_TIMEOUT`, Monitoring probe timeout, `30s`
`SERVER_MONITORING_TLS_ROOT_CA_FILE`, Monitoring TLS root CA file
`SERVER_SAMPLING_ENABLED`, Enable sampling, `false`
`SERVER_SAMPLING_RATE`, Sampling rate, `1.0`
`SERVER_OPERATIONS_JITTER`, Operations jitter in milliseconds, `0`
`SERVER_OPERATIONS_POLL_INTERVAL`, Operations poll interval in seconds, `2`

## Cron Operations Configuration

Variable, Description, Default Value

`SERVER_CRON_OPERATIONS_TASK_ANALYZE_CRON_INTERVAL`, Interval for running ANALYZE on task-related tables, `3h`
`SERVER_CRON_OPERATIONS_OLAP_ANALYZE_CRON_INTERVAL`, Interval for running ANALYZE on OLAP/analytics tables, `3h`
`SERVER_CRON_OPERATIONS_DB_HEALTH_METRICS_INTERVAL`, Interval for collecting database health metrics (OTel), `60s`
`SERVER_CRON_OPERATIONS_OLAP_METRICS_INTERVAL`, Interval for collecting OLAP metrics (OTel), `5m`
`SERVER_CRON_OPERATIONS_WORKER_METRICS_INTERVAL`, Interval for collecting worker metrics (OTel), `60s`
`SERVER_CRON_OPERATIONS_YESTERDAY_RUN_COUNT_HOUR`, Hour (0-23) at which to collect yesterday's workflow run count (OTel), `0`
`SERVER_CRON_OPERATIONS_YESTERDAY_RUN_COUNT_MINUTE`, Minute (0-59) at which to collect yesterday's workflow run count, `5`
`SERVER_WAIT_FOR_FLUSH`, Default wait for flush, `1ms`
`SERVER_MAX_CONCURRENT`, Default max concurrent, `50`
`SERVER_FLUSH_PERIOD_MILLISECONDS`, Default flush period, `10ms`
`SERVER_FLUSH_ITEMS_THRESHOLD`, Default flush threshold, `100`
`SERVER_FLUSH_STRATEGY`, Default flush strategy, `DYNAMIC`

## OLAP Database Configuration

Variable, Description, Default Value

`SERVER_OLAP_STATUS_UPDATE_DAG_BATCH_SIZE_LIMIT`, Batch size limit for running DAG status updates, `1000`
`SERVER_OLAP_STATUS_UPDATE_TASK_BATCH_SIZE_LIMIT`, Batch size limit for running task status updates, `1000`