Environment Variables

Required

Variable	Used by	Default	Description
API_KEY	API	-	Bearer token required for authenticated /v1/* API requests.
DATABASE_URL	API/worker	Local test database URL	PostgreSQL connection string. Set explicitly outside local development.

hub-worker requires an explicit DATABASE_URL; it does not use the local test default.

Server

Variable	Default	Description
PORT	8080	HTTP port used inside the API process/container.
PUBLIC_BASE_URL	-	Public API root advertised in runtime OpenAPI specs when Hub is behind ingress, TLS, or a path prefix.
LOG_LEVEL	info	Log level, such as debug, info, warn, or error.
SHUTDOWN_TIMEOUT_SECONDS	30	Graceful shutdown timeout in seconds.

The Quick Start Docker Compose file also supports HUB_PORT, POSTGRES_PORT, and HUB_IMAGE_TAG as Compose conveniences. They are compose variables, not Hub runtime settings.

PUBLIC_BASE_URL must be an absolute http or https URL. It may include a path prefix, such as https://example.com/hub, but must not include query strings, fragments, or credentials. Hub serves runtime OpenAPI specs at /openapi.yaml and /openapi.json.

Database Pool

Variable	Default	Description
DATABASE_MAX_CONNS	25	Maximum PostgreSQL pool connections.
DATABASE_MIN_CONNS	0	Minimum PostgreSQL pool connections.
DATABASE_MAX_CONN_LIFETIME_SECONDS	3600	Maximum connection lifetime.
DATABASE_MAX_CONN_IDLE_TIME_SECONDS	1800	Maximum idle time before a connection is closed.
DATABASE_HEALTH_CHECK_PERIOD_SECONDS	60	Pool health-check interval.
DATABASE_CONNECT_TIMEOUT_SECONDS	10	Database connection timeout.

River Worker

Variable	Default	Description
RIVER_JOB_TIMEOUT_SECONDS	0	Max job runtime before cancellation; 0 uses the River default.
RIVER_RESCUE_STUCK_JOBS_AFTER_SECONDS	0	Stuck-job rescue interval; 0 uses the River default.
RIVER_COMPLETED_JOB_RETENTION_SECONDS	86400	Completed job retention period; -1 disables deletion.
RIVER_CLIENT_ID	-	Optional client identifier for logs and River coordination.

Webhooks

Variable	Default	Description
WEBHOOK_DELIVERY_MAX_CONCURRENT	100	Max concurrent webhook delivery workers.
WEBHOOK_DELIVERY_MAX_ATTEMPTS	3	Max delivery attempts per webhook job.
WEBHOOK_MAX_FAN_OUT_PER_EVENT	500	Max webhook jobs inserted for a single event batch.
WEBHOOK_MAX_COUNT	500	Max total webhook endpoints allowed.
WEBHOOK_HTTP_TIMEOUT_SECONDS	15	Outbound webhook request timeout.
WEBHOOK_ENQUEUE_MAX_RETRIES	3	Retries when enqueueing webhook jobs fails.
WEBHOOK_ENQUEUE_INITIAL_BACKOFF_MS	100	Initial enqueue retry backoff in milliseconds.
WEBHOOK_ENQUEUE_MAX_BACKOFF_MS	2000	Maximum enqueue retry backoff in milliseconds.
WEBHOOK_BLACKLIST	localhost,127.0.0.1,::1,169.254.169.254	Comma-separated hostnames blocked for webhook URLs.

Event Publisher

Variable	Default	Description
MESSAGE_PUBLISHER_QUEUE_MAX_SIZE	16384	In-memory event channel buffer size.
MESSAGE_PUBLISHER_PER_EVENT_TIMEOUT_SECONDS	10	Per-event publish timeout in seconds.

Embeddings

Variable	Default	Description
EMBEDDING_PROVIDER	-	Embedding provider. One of openai, google, or google-vertex.
EMBEDDING_PROVIDER_API_KEY	-	API key for the embedding provider.
EMBEDDING_MODEL	-	Embedding model name.
EMBEDDING_MAX_CONCURRENT	5	Max concurrent embedding jobs.
EMBEDDING_MAX_ATTEMPTS	3	Max embedding attempts.
EMBEDDING_NORMALIZE	false	Whether to normalize embeddings before storage.
EMBEDDING_GOOGLE_CLOUD_PROJECT	-	Google Cloud project for supported providers.
EMBEDDING_GOOGLE_CLOUD_LOCATION	-	Google Cloud location for supported providers.

Observability

Variable	Default	Description
OTEL_METRICS_EXPORTER	-	OpenTelemetry metrics exporter.
OTEL_TRACES_EXPORTER	-	OpenTelemetry traces exporter.

MCP Client Package

These variables are used by MCP client package flows. They are not read by the Hub API or worker processes.

Variable	Default	Description
HUB_API_KEY	-	API key used by MCP clients; usually the same value as Hub’s API_KEY.
FORMBRICKS_HUB_BASE_URL	-	Hub API root reachable from the MCP server, for example https://hub.example.com.

See Connect Hub to AI Clients via MCP for client setup.