Add to Cursor Add to Claude Copy for LLM View as MD

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

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

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

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)

SERVER_AUTH_COOKIE_SECRETS="<secret1> <secret2>"

Database Connection (Required)

Option A: Connection String

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

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

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

Minimal Configuration Example

⚠️

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.

# 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:

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

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`

High Availability Prometheus Metrics

We use cookies