Configuration

Reading with an LLM? Give it this page as Markdown: http://localhost/docs/self-hosting/configuration.md

kraken is configured with environment variables, which are substituted into its sys.config when the release starts. The defaults below are the ones baked into kraken's Docker image. A few settings exist only in sys.config; they are listed at the end of this page.

The repository's docker-compose.yml passes only AUTH_ALLOW_ALL through from your shell. To set anything else, add it under environment: in a compose file, or pass -e NAME=value to docker run.

This page describes v0.9.0. Where kraken's own docs/CONFIG.md says otherwise, this page reflects what the code does.

Listeners

Variable	Default	Meaning
`WS_PORT`	`8080`	HTTP port: the WebSocket endpoint `/ws` and the health check `/health`
`MQTT_PORT`	`1883`	Port for kraken's MQTT 3.1.1 listener. No MQTT client can connect in v0.9.0: the connection handler fails to start for every connection. Do not expose this port.

Backends

Variable	Default	Values
`AUTH_BACKEND`	`static`	`static` (a token file), `http` (your service), or an Erlang module name. See Static Auth File and HTTP Auth Contract.
`BROKER_BACKEND`	`syn`	`syn` (built in, no dependencies) or `mqtt` (an external MQTT broker), or a module name. `syn` ignores QoS; `mqtt` passes it to the external broker. See Scaling and MQTT.
`STORE_BACKEND`	`ets`	`ets` (in memory) or `noop`, or a module name. Where recorded messages go.
`CONTROL_BACKEND`	`noop`	`noop` or `http`, or a module name. Usage, subscription and webhook-failure reports. See Plugins.

Auth and control plane

Variable	Default	Meaning
`AUTH_FILE`	`/app/examples/auth.json`	Token file for the `static` backend
`AUTH_ALLOW_ALL`	`false`	Accept any token with access to every topic. Insecure; local development only.
`AUTH_HTTP_URL`	empty	Base URL for the `http` auth backend. Its path is kept.
`CONTROL_HTTP_URL`	empty	Base URL for the `http` control backend
`BACKEND_SECRET`	empty	Sent as `Authorization: Bearer <secret>` to both HTTP backends

MQTT broker backend

Used only with BROKER_BACKEND=mqtt.

Variable	Default	Meaning
`MQTT_BROKER_HOST`	empty	Host of the external MQTT broker
`MQTT_BROKER_PORT`	`1884`	Its port. Most brokers listen on `1883`, so you will usually set this.
`MQTT_BROKER_USERNAME`, `MQTT_BROKER_PASSWORD`	empty	Credentials, if the broker wants them

Message recording

Variable	Default	Meaning
`RECORD_MESSAGES`	`true`	When on, kraken gives every publish a message id and writes it to the store backend. Deliveries then carry `msgId` and `requiresAck: true`, and the SDKs acknowledge them. Nothing in v0.9.0 lets a client read recorded messages back, so for most deployments this only costs memory. The nolag-core quickstart turns it off.
`STORE_TTL_SECONDS`	`3600`	`ets` store: how long a recorded message is kept
`STORE_MAX_MESSAGES`	`10000`	`ets` store: above this many messages, the oldest tenth is dropped

Limits

Variable	Default	Meaning
`MAX_MESSAGE_SIZE`	`921600`	Not enforced in v0.9.0. Every publish is held to a fixed 921,600 byte ceiling whatever this says, and the same goes for per-token sizes from an auth backend.

Internal

Variable	Default	Meaning
`INTERNAL_SECRET`	`change_me`	Guards an internal HTTP endpoint on the WebSocket port. It is internal and unsupported: do not build on it. Change the default anyway, and do not route `/internal/` through your reverse proxy.

Clustering

See Scaling and MQTT for how these fit together.

Variable	Default	Meaning
`CLUSTER_STRATEGY`	`standalone`	`standalone`, `epmd` or `dns`. `gossip` is accepted but does not form a cluster in v0.9.0.
`CLUSTER_HOSTS`	empty	`epmd`: comma-separated full node names of the peers
`CLUSTER_DNS_QUERY`	empty	`dns`: a name whose A records are the peers' IP addresses
`CLUSTER_NODE_BASENAME`	`kraken_proxy`	`dns`: the part before `@` in each peer's node name. Set it to match your nodes' `ERLANG_NODE_NAME`.
`CLUSTER_POLL_INTERVAL`	`30000`	Milliseconds between discovery attempts
`ERLANG_NODE_NAME`	`kraken@127.0.0.1`	This node's full name. kraken runs with long names, so the part after `@` must be a fully qualified domain name or an IP address.
`ERLANG_COOKIE`	`kraken_dev_cookie`	Shared secret between nodes; must match across the cluster. Change it.
`CLUSTER_GOSSIP_PORT`, `CLUSTER_MULTICAST_ADDR`	`45892`, `230.1.1.1`	Used only by `gossip`, which does not work in v0.9.0

kraken's docs/CONFIG.md also lists CLUSTER_DNS_NAME and CLUSTER_GOSSIP_SECRET. Nothing in v0.9.0 reads either; DNS discovery uses CLUSTER_DNS_QUERY.

Fixed limits

These are constants in the code, the same for every connection whatever the auth backend returns. We measured each of the first four against v0.9.0.

Limit	Value	When exceeded
Publishes per connection	50 per second	The rest of that second's publishes are refused with error `42910`, `rate_limit_exceeded`. Other frame types do not count.
Publish payload	921,600 bytes, measured as packed MessagePack	Refused with error `42930`, `message_too_large`, carrying `maxSizeBytes`
WebSocket frame	1 MiB (1,048,576 bytes)	The connection is closed with code `1009`
Idle connection	60 seconds without any frame from the client	The connection is closed with code `1000`. The SDKs send a heartbeat every 30 seconds.
Auth cache	30 seconds per token	Successful validations only
Revalidation	Every 10 minutes per connection	Checked on the client's heartbeats
Filters	100 per subscription	Refused with `too_many_filters (max 100)`
Retained messages (`syn` broker)	The last one per topic, kept 1 hour, in memory
Room-access check	2 second timeout; refusals remembered for 5 seconds	Configurable in `sys.config`

Settings only in sys.config

These have no environment variable. Change them by editing config/sys.config.src and rebuilding the image, or in the sys.config of an application that embeds kraken.

Key	Default	Meaning
`cache_miss_fallback_enabled`	`true`	Ask the auth backend's `/check-room-access` when a subscribe misses the cached grants
`cache_miss_fallback_timeout_ms`	`2000`	Timeout for that check
`acl_deny_cache_ttl_ms`	`5000`	How long a refused check is remembered per actor and address
`release_shared_subs_on_close`	`true`	Release a closing connection's load-balanced subscriptions. Applies only to persistent sessions with durable delivery on.
`fallback_compat`	`true`	Wildcard-resolved subscriptions also listen on the topic names used by brokers older than protocol version 2, for rolling upgrades
`presence_store_backend`, `wake_backend`, `delivery_store_backend`	`noop`	Plugin slots without an environment variable. See Plugins.
`durable_delivery`	`false`	Must be `true` for a delivery store backend to take effect
`wake_secret`	empty	Signing secret for the `kraken_wake_http` module

The @nolag/core example host

The example host in the nolag-core repository reads these. CoreModule itself reads no environment variables; a host passes it what it needs.

Variable	Default	Meaning
`PORT`	`3000`	HTTP port
`POSTGRES_HOST`, `POSTGRES_PORT`	`localhost`, `5432`	Database address
`POSTGRES_SOCKET_PATH`	empty	A Unix socket directory; takes precedence over host and port
`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE`	none	Required
`POSTGRES_POOL_MIN`, `POSTGRES_POOL_MAX`	`1`, `10`	Connection pool size
`SKIP_MIGRATIONS`	`false`	Set to `true` to skip applying core's migrations at startup
`SIGNING_KEY_ENCRYPTION_KEY`	empty	32 random bytes, base64. Needed for signing keys and client tokens.
`CORS_ORIGINS`	empty	Comma-separated origins allowed to call the host from a browser. `*` is ignored.
`DEFAULT_MAX_CONNECTIONS`	unlimited	Connection limit for projects whose document set no limits
`DEFAULT_MAX_MESSAGE_SIZE_BYTES`	unlimited	Passed to kraken, which does not enforce it
`DEFAULT_SESSION_EXPIRY_SECONDS`	`3600`	Session expiry for `agent` and `orchestrator` actors