Advanced Configuration

This page is the canonical public reference for every supported server.toml key and every documented KALAMDB_* runtime override.

Use it when you need exact key names, actual defaults, or a clear answer to whether a setting is configured through TOML, an environment variable, or both.

Before You Start

If you are new to setup, start with /docs/server/getting-started/configuration.
If you want the fully commented sample file, download server.example.toml (full commented sample) .
The tables below show the real defaults from the config crate. The checked-in sample config may intentionally use different values for local development, CI, or demo environments.

Focused guides:

Loading Order

Load server.toml.
Apply config-loader environment overrides from KALAMDB_* variables.
Apply runtime-only environment behavior that lives outside the config crate.
Normalize paths and validate the final configuration.

Runtime-only env vars are currently:

KALAMDB_ROOT_PASSWORD for root bootstrap password selection during startup.
KALAMDB_TOKIO_WORKER_THREADS for overriding Tokio runtime worker threads.

Environment Override Reference

Only the variables below are supported today. If a setting is not listed here, configure it in server.toml.

Boolean parsing notes:

Most positive boolean env vars treat true, 1, and yes as enabled.
KALAMDB_COOKIE_SECURE is inverted for convenience: false, 0, and no disable it; any other non-empty value enables it.

List parsing notes:

KALAMDB_SECURITY_CORS_ALLOWED_ORIGINS and KALAMDB_SECURITY_TRUSTED_PROXY_RANGES accept comma-separated values.
KALAMDB_CLUSTER_PEERS accepts node_id@rpc_addr@api_addr[@rpc_server_name] entries separated by semicolons.

Server, Logging, and Storage

Environment variable	Maps to	Notes
`KALAMDB_SERVER_HOST`	`server.host`	Bind host/interface.
`KALAMDB_SERVER_PORT`	`server.port`	HTTP listen port.
`KALAMDB_SERVER_PUBLIC_ORIGIN`	`server.public_origin`	Empty string preserves browser-origin fallback behavior.
`KALAMDB_SERVER_WORKERS`	`server.workers`	Actix worker threads.
`KALAMDB_LOG_LEVEL`	`logging.level`	`error`, `warn`, `info`, `debug`, `trace`.
`KALAMDB_LOG_FORMAT`	`logging.format`	`compact`, `pretty`, or `json`.
`KALAMDB_LOGS_DIR`	`logging.logs_path`	Directory for `server.log`, `server.jsonl`, and `slow.log`.
`KALAMDB_LOG_TO_CONSOLE`	`logging.log_to_console`	Also emit logs to stdout/stderr.
`KALAMDB_SLOW_QUERY_THRESHOLD_MS`	`logging.slow_query_threshold_ms`	Slow query threshold in milliseconds.
`KALAMDB_OTLP_ENABLED`	`logging.otlp.enabled`	Enable OTLP trace export.
`KALAMDB_OTLP_ENDPOINT`	`logging.otlp.endpoint`	Collector endpoint.
`KALAMDB_OTLP_PROTOCOL`	`logging.otlp.protocol`	`grpc` or `http`.
`KALAMDB_OTLP_SERVICE_NAME`	`logging.otlp.service_name`	Service name shown by the collector/backend.
`KALAMDB_OTLP_TIMEOUT_MS`	`logging.otlp.timeout_ms`	OTLP export timeout.
`KALAMDB_DATA_DIR`	`storage.data_path`	Base data directory.

Topics, Auth, Security, and WebSockets

Environment variable	Maps to	Notes
`KALAMDB_TOPIC_VISIBILITY_TIMEOUT_SECS`	`topics.visibility_timeout_secs`	Canonical topic visibility timeout override.
`KALAMDB_VISIBILITY_TIMEOUT_SECS`	`topics.visibility_timeout_secs`	Legacy compatibility alias.
`KALAMDB_TOPIC_DEFAULT_RETENTION_SECONDS`	`topics.default_retention_seconds`	Default topic time retention.
`KALAMDB_TOPIC_DEFAULT_RETENTION_MAX_BYTES`	`topics.default_retention_max_bytes`	Default topic byte retention.
`KALAMDB_TOPIC_RETENTION_CHECK_INTERVAL_SECONDS`	`topics.retention_check_interval_seconds`	Scheduler interval.
`KALAMDB_TOPIC_RETENTION_BATCH_SIZE`	`topics.retention_batch_size`	Delete batch size.
`KALAMDB_JWT_SECRET`	`auth.jwt_secret`	Internal JWT signing/verification secret.
`KALAMDB_JWT_TRUSTED_ISSUERS`	`auth.jwt_trusted_issuers`	Comma-separated issuer list.
`KALAMDB_JWT_EXPIRY_HOURS`	`auth.jwt_expiry_hours`	Internal token TTL.
`KALAMDB_COOKIE_SECURE`	`auth.cookie_secure`	HTTPS-only auth cookies.
`KALAMDB_ALLOW_REMOTE_SETUP`	`auth.allow_remote_setup`	Enables first-time setup from non-localhost clients.
`KALAMDB_PG_AUTH_TOKEN`	`auth.pg_auth_token`	Pre-shared token for `pg_kalam` gRPC auth.
`KALAMDB_AUTH_OIDC_AUTO_PROVISION`	`auth.oidc.auto_provision`	OIDC auto-provisioning override.
`KALAMDB_SECURITY_CORS_ALLOWED_ORIGINS`	`security.cors.allowed_origins`	Comma-separated list or `*`.
`KALAMDB_SECURITY_TRUSTED_PROXY_RANGES`	`security.trusted_proxy_ranges`	Canonical proxy trust override.
`KALAMDB_TRUSTED_PROXY_RANGES`	`security.trusted_proxy_ranges`	Legacy env alias kept for compatibility.
`KALAMDB_RATE_LIMIT_AUTH_REQUESTS_PER_IP_PER_SEC`	`rate_limit.max_auth_requests_per_ip_per_sec`	Brute-force protection rate limit.
`KALAMDB_WEBSOCKET_CLIENT_TIMEOUT_SECS`	`websocket.client_timeout_secs`	Client heartbeat timeout.
`KALAMDB_WEBSOCKET_AUTH_TIMEOUT_SECS`	`websocket.auth_timeout_secs`	Time allowed before auth message arrives.
`KALAMDB_WEBSOCKET_HEARTBEAT_INTERVAL_SECS`	`websocket.heartbeat_interval_secs`	Heartbeat scan interval.

Cluster and RPC TLS

Environment variable	Maps to	Notes
`KALAMDB_CLUSTER_ID`	`cluster.cluster_id`	Creates the cluster section if needed.
`KALAMDB_NODE_ID`	`cluster.node_id`	Canonical node ID override.
`KALAMDB_CLUSTER_NODE_ID`	`cluster.node_id`	Legacy alias for `KALAMDB_NODE_ID`.
`KALAMDB_CLUSTER_RPC_ADDR`	`cluster.rpc_addr`	Advertised Raft RPC address.
`KALAMDB_CLUSTER_API_ADDR`	`cluster.api_addr`	Advertised API address.
`KALAMDB_CLUSTER_PEERS`	`cluster.peers`	`node_id@rpc_addr@api_addr[@rpc_server_name];...`
`KALAMDB_RPC_TLS_ENABLED`	`rpc_tls.enabled`	Enable TLS/mTLS on the gRPC listener.
`KALAMDB_RPC_TLS_CA_CERT`	`rpc_tls.ca_cert`	File path or inline PEM.
`KALAMDB_RPC_TLS_SERVER_CERT`	`rpc_tls.server_cert`	File path or inline PEM.
`KALAMDB_RPC_TLS_SERVER_KEY`	`rpc_tls.server_key`	File path or inline PEM.
`KALAMDB_RPC_TLS_REQUIRE_CLIENT_CERT`	`rpc_tls.require_client_cert`	Require client certs signed by `ca_cert`.

Runtime-Only Environment Variables

Environment variable	Effect	Notes
`KALAMDB_ROOT_PASSWORD`	Sets the initial root password during startup bootstrap.	This does not come from `apply_env_overrides`; it is read in server lifecycle startup. It takes precedence over `auth.root_password`.
`KALAMDB_TOKIO_WORKER_THREADS`	Overrides Tokio runtime worker thread count.	This is read in the server binary and takes precedence over `performance.tokio_worker_threads`.

Full `server.toml` Reference

Top-Level Keys

Key	Default	Description
`transaction_timeout_secs`	`300`	Maximum lifetime of an open transaction before the server aborts it.
`max_transaction_buffer_bytes`	`104857600` (100 MB)	Maximum in-memory transaction overlay size before new writes are rejected.

`[server]`

Key	Default	Description
`host`	`"127.0.0.1"`	Network interface to bind. Use `0.0.0.0` only with explicit CORS/origin policy.
`port`	`2900`	HTTP port for REST, SQL, auth, and WebSocket entrypoints.
`public_origin`	unset	Public browser-facing origin used by the Admin UI for `/v1/api` and `/v1/ws`.
`workers`	`0`	Actix worker threads. `0` means automatic sizing.
`api_version`	`"v1"`	Version prefix for API routes.
`enable_http2`	`true`	Enables HTTP/1.1 + cleartext HTTP/2 negotiation.
`ui_path`	unset	Path to a built Admin UI bundle to serve from the server.

`[storage]`

Key	Default	Description
`data_path`	`"./data"`	Base path for RocksDB, Parquet storage, snapshots, streams, exports, and temp files.
`shared_tables_template`	`"{namespace}/{tableName}"`	Folder template for shared tables.
`user_tables_template`	`"{namespace}/{tableName}/{userId}"`	Folder template for user-scoped tables.

`[storage.remote_timeouts]`

Key	Default	Description
`request_timeout_secs`	`60`	Request timeout for remote storage backends.
`connect_timeout_secs`	`10`	Connection timeout for remote storage backends.

`[storage.rocksdb]`

Key	Default	Description
`block_cache_size`	`2097152` (2 MB)	Shared RocksDB read block cache across all column families.
`max_background_jobs`	`4`	Background compaction and flush worker count.
`max_open_files`	`512`	Maximum open files kept by RocksDB. `-1` means unlimited.
`sync_writes`	`false`	Fsync WAL on each write for stronger durability and lower throughput.
`disable_wal`	`false`	Disables WAL for speed at the cost of crash recovery guarantees.
`compact_on_startup`	`false`	Compact column families during startup to reduce SST spread. Disabled by default to keep startup fast.

`[storage.rocksdb.cf_profiles.system_meta]`

Key	Default	Description
`write_buffer_size`	`32768`	Write buffer size for system metadata CFs.
`max_write_buffers`	`2`	Max RocksDB memtables for system metadata CFs.

`[storage.rocksdb.cf_profiles.system_index]`

Key	Default	Description
`write_buffer_size`	`32768`	Write buffer size for system index CFs.
`max_write_buffers`	`2`	Max RocksDB memtables for system index CFs.

`[storage.rocksdb.cf_profiles.hot_data]`

Key	Default	Description
`write_buffer_size`	`131072`	Write buffer size for hot data CFs.
`max_write_buffers`	`2`	Max RocksDB memtables for hot data CFs.

`[storage.rocksdb.cf_profiles.hot_index]`

Key	Default	Description
`write_buffer_size`	`65536`	Write buffer size for hot index CFs.
`max_write_buffers`	`2`	Max RocksDB memtables for hot index CFs.

`[storage.rocksdb.cf_profiles.raft]`

Key	Default	Description
`write_buffer_size`	`262144`	Write buffer size for the Raft CF.
`max_write_buffers`	`2`	Max RocksDB memtables for the Raft CF.

`[datafusion]`

Key	Default	Description
`memory_limit`	`33554432` (32 MB)	Query execution memory budget.
`query_parallelism`	`2`	Query execution worker concurrency.
`max_partitions`	`4`	Maximum partitions used in planning and scans.
`batch_size`	`1024`	Record batch size for execution operators.

`[flush]`

Key	Default	Description
`default_row_limit`	`10000`	Row threshold that triggers flush when no per-table override exists.
`default_time_interval`	`300`	Time threshold in seconds for automatic flush.
`flush_batch_size`	`10000`	Rows loaded into memory per flush batch.
`check_interval_seconds`	`60`	Scheduler scan interval for pending writes. `0` disables the scheduler.

`[flush.compaction]`

Optional post-flush Parquet compaction for trailing small segments. This is configured in server.toml; there are no dedicated KALAMDB_* overrides for these keys today.

For the architecture behind these settings, see /docs/server/architecture/storage-tiers and /docs/server/architecture/manifests.

Key	Default	Description
`enabled`	`false`	Enable leader-only post-flush compaction for eligible `USER` and `SHARED` table scopes.
`min_eligible_segments`	`5`	Minimum number of newest trailing small segments required before a compaction job is considered.
`max_segments_per_run`	`8`	Maximum number of newest trailing segments rewritten by one compaction job.
`user_max_segment_rows`	`10000`	User-table segments below this row count are considered small.
`shared_max_segment_rows`	`25000`	Shared-table segments below this row count are considered small.

Compaction rewrites only the manifest tail: newest committed segments on the same schema version and below the configured row target. If a newer flush changes that tail while compaction is writing, the swap is skipped and the compacted output is discarded.

`[retention]`

Key	Default	Description
`enable_dba_stats`	`true`	Enables background `dba.stats` collection.
`dba_stats_retention_days`	`7`	Number of days to retain `dba.stats` samples. `0` disables automatic cleanup.

`[stream]`

Key	Default	Description
`default_ttl_seconds`	`10`	Default lifetime of stream rows/events.
`default_max_buffer`	`10000`	Default in-memory stream buffer limit.
`eviction_interval_seconds`	`60`	Background eviction interval for expired stream data.

`[manifest_cache]`

Manifest cache behavior is explained in /docs/server/architecture/manifests.

Key	Default	Description
`eviction_interval_seconds`	`300`	Interval between manifest cache eviction passes.
`max_entries`	`500`	Maximum hot manifest entries kept in memory.
`eviction_ttl_days`	`7`	Age after which unused manifest entries are evicted.

`[limits]`

Key	Default	Description
`max_message_size`	`1048576` (1 MB)	Maximum accepted request payload/message size.
`max_query_limit`	`1000`	Hard maximum `LIMIT` the server will accept.
`default_query_limit`	`50`	Implicit `LIMIT` when the query omits one.

`[logging]`

For end-to-end examples and deployment guidance, use /docs/server/configurations/logging.

Key	Default	Description
`level`	`"info"`	Global log verbosity.
`logs_path`	`"./logs"`	Directory for server log files.
`log_to_console`	`true`	Also emit logs to stdout/stderr.
`format`	`"compact"`	`compact`, `pretty`, or `json`.
`slow_query_threshold_ms`	`1200`	Slow query threshold in milliseconds.

[logging.targets] is an optional dynamic table of per-target log levels, for example:

TOML

1[logging.targets]2datafusion = "warn"3arrow = "warn"4parquet = "warn"

`[logging.otlp]`

Key	Default	Description
`enabled`	`false`	Enables OpenTelemetry trace export.
`endpoint`	`"http://127.0.0.1:4317"`	Collector endpoint.
`protocol`	`"grpc"`	OTLP transport: `grpc` or `http`.
`service_name`	`"kalamdb-server"`	Service name attached to exported spans.
`timeout_ms`	`3000`	OTLP export timeout in milliseconds.

`[performance]`

Key	Default	Description
`request_timeout`	`30`	Maximum full request execution time in seconds.
`keepalive_timeout`	`75`	Idle HTTP keep-alive timeout in seconds.
`max_connections`	`25000`	Maximum simultaneous client connections.
`backlog`	`4096`	Kernel listen backlog for pending TCP connections.
`tokio_worker_threads`	`0`	Tokio runtime worker threads. `0` means auto-size, capped in the binary.
`worker_max_blocking_threads`	`32`	Per-worker cap for blocking tasks such as RocksDB I/O.
`client_request_timeout`	`5`	Time allowed for a client to finish sending request headers.
`client_disconnect_timeout`	`2`	Graceful client disconnect timeout.
`max_header_size`	`16384` (16 KB)	Maximum HTTP header size.

`[rate_limit]`

Key	Default	Description
`max_queries_per_sec`	`100`	Per-user SQL query rate limit.
`max_messages_per_sec`	`50`	Per-WebSocket incoming message rate limit.
`max_subscriptions_per_user`	`10`	Maximum live subscriptions per user.
`max_auth_requests_per_ip_per_sec`	`20`	Rate limit for auth/setup endpoints per IP.
`max_connections_per_ip`	`100`	Maximum concurrent connections per IP.
`max_requests_per_ip_per_sec`	`200`	Pre-auth request flood protection per IP.
`request_body_limit_bytes`	`10485760` (10 MB)	Request body cap used by connection protection.
`ban_duration_seconds`	`300`	Temporary IP ban duration after repeated abuse.
`enable_connection_protection`	`true`	Master switch for connection abuse protection.
`cache_max_entries`	`1000`	Maximum cached rate-limit entries.
`cache_ttl_seconds`	`600`	Idle TTL for cached rate-limit entries.

`[security]`

Key	Default	Description
`trusted_proxy_ranges`	`[]`	Proxy IPs or CIDR ranges allowed to supply forwarded client IP headers.
`max_ws_message_size`	`1048576` (1 MB)	Maximum accepted WebSocket message size.
`strict_ws_origin_check`	`false`	Reject WebSocket connections that lack a valid `Origin` header.
`max_request_body_size`	`10485760` (10 MB)	Global HTTP request body cap.

`[security.cors]`

Key	Default	Description
`allowed_origins`	`[]`	Allowed browser origins. Empty behaves like wildcard at runtime, but non-localhost startup validation requires explicit origins.
`allowed_methods`	`["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]`	Allowed CORS methods.
`allowed_headers`	`["Authorization", "Content-Type", "Accept", "Origin", "X-Requested-With"]`	Allowed browser request headers.
`expose_headers`	`[]`	Response headers exposed to browser JavaScript.
`allow_credentials`	`false`	Allow cookies or authorization headers on CORS requests.
`max_age`	`3600`	Preflight cache duration in seconds.
`allow_private_network`	`false`	Enables private network preflight support where browsers implement it.

`[websocket]`

Key	Default	Description
`client_timeout_secs`	`10`	Maximum time without client heartbeat activity before disconnect.
`auth_timeout_secs`	`3`	Time allowed after connect before auth must arrive.
`heartbeat_interval_secs`	`5`	Interval between heartbeat scans/pings.

`[auth]` or `[authentication]`

Both section names are accepted. The config crate stores them as auth internally.

Key	Default	Description
`root_password`	unset	Config-file root bootstrap password. Runtime env `KALAMDB_ROOT_PASSWORD` takes precedence.
`jwt_secret`	`"CHANGE_ME_IN_PRODUCTION"`	Secret for signing and validating internal HS256 tokens.
`jwt_trusted_issuers`	`""`	Comma-separated trusted external issuer list.
`jwt_expiry_hours`	`24`	Lifetime of internal JWTs in hours.
`cookie_secure`	`true`	Restricts auth cookies to HTTPS.
`allow_remote_setup`	`false`	Allow first-time setup from non-localhost clients.
`pg_auth_token`	unset	Pre-shared token for `pg_kalam` gRPC authentication.

Compatibility note: older configs may still contain a pre-rename password-policy key; the current supported key is auth.local.enforce_password_complexity.

`[auth.local]`

Key	Default	Description
`enabled`	`true`	Enables local username/password login and password setup.
`bcrypt_cost`	`12`	Password hash work factor. Valid range is determined by bcrypt.
`min_password_length`	`8`	Minimum accepted password length.
`max_password_length`	`1024`	Maximum locally accepted password length.
`enforce_password_complexity`	`false`	Require uppercase, lowercase, digit, and special characters in passwords.

`[auth.oidc]`

KalamDB supports one external OpenID Connect provider per server process.

Key	Default	Description
`enabled`	`false`	Enables the configured OIDC provider.
`display_name`	unset	Human-facing provider label for UI and CLI login.
`issuer`	unset	OIDC issuer URL. Must be included in `auth.jwt_trusted_issuers`.
`client_id`	unset	Client ID used for browser/device flows and default audience validation.
`client_secret`	unset	Client secret for confidential clients or brokered provider exchanges.
`scopes`	`["openid", "email", "profile"]`	OIDC scopes. Must include `openid`.
`device_authorization_endpoint`	unset	Optional device-flow endpoint override when discovery omits it.
`broker_device_flow_enabled`	`false`	Enables KalamDB-brokered OIDC device flow.
`auto_provision`	`false`	Allows absent regular OIDC subjects when default role is `user`; creates rows for elevated default roles.
`default_role`	`"user"`	Role used for auto-provisioned OIDC users.
`audience`	unset	Explicit audience override; defaults to `client_id`.

`[user_management]`

Key	Default	Description
`deletion_grace_period_days`	`30`	Grace period before soft-deleted users are purged.
`cleanup_job_schedule`	`"0 2 * * *"`	Cron schedule for user cleanup.

`[files]`

Key	Default	Description
`max_size_bytes`	`26214400` (25 MB)	Maximum size of a single uploaded file.
`max_files_per_request`	`20`	Maximum uploaded files accepted in one request.
`max_files_per_folder`	`5000`	Folder rotation threshold for durable file storage.
`staging_path`	`"./data/tmp"`	Temporary upload staging directory.
`allowed_mime_types`	`[]`	Allowed MIME types. Empty means allow all.

`[shutdown.flush]`

Key	Default	Description
`timeout`	`300`	Maximum wait time in seconds for flush jobs during graceful shutdown.

`[jobs]`

Key	Default	Description
`max_concurrent`	`10`	Maximum concurrently running background jobs.
`max_retries`	`3`	Retry attempts before a job is marked failed.
`retry_backoff_ms`	`100`	Initial retry backoff in milliseconds.
`wal_cleanup_interval_seconds`	`300`	Interval for memtable flushes that reclaim stale WAL files. `0` disables it.

`[execution]`

Key	Default	Description
`handler_timeout_seconds`	`30`	Maximum execution handler duration in seconds.
`max_parameters`	`50`	Maximum parameter count per statement.
`max_parameter_size_bytes`	`524288` (512 KB)	Maximum size of a single parameter value.
`sql_plan_cache_max_entries`	`200`	Maximum cached SQL logical plans.
`sql_plan_cache_ttl_seconds`	`900`	Idle TTL for cached SQL logical plans.

`[topics]`

Key	Default	Description
`visibility_timeout_secs`	`60`	Hide unacknowledged consumer claims for this many seconds before redelivery.
`default_retention_seconds`	`604800` (7 days)	Default topic time retention.
`default_retention_max_bytes`	`1073741824` (1 GiB)	Default topic byte retention per partition.
`retention_check_interval_seconds`	`3600`	Topic retention scheduler interval in seconds. `0` disables scheduling.
`retention_batch_size`	`10000`	Maximum deletes per partition in a single retention pass.

`[rpc_tls]`

This secures the shared gRPC listener used by Raft replication, cluster RPC, and the PostgreSQL extension.

Key	Default	Description
`enabled`	`false`	Enable TLS or mTLS on the gRPC listener.
`ca_cert`	unset	CA certificate used to validate incoming client certificates. File path or inline PEM.
`server_cert`	unset	Server certificate. File path or inline PEM.
`server_key`	unset	Private key for `server_cert`. File path or inline PEM.
`require_client_cert`	`true`	Require clients to present a CA-signed certificate.

`[cluster]`

Omit this section entirely for standalone mode.

For the Multi-Raft model behind these options, see /docs/server/architecture/clustering.

Key	Default	Description
`cluster_id`	`"cluster"`	Logical cluster identifier shared by all nodes.
`node_id`	required	Unique node ID for this server. Must be greater than `0`.
`rpc_addr`	`"127.0.0.1:2910"`	Advertised Raft RPC address. Use a reachable address, not a wildcard, in real clusters.
`api_addr`	`"0.0.0.0:2900"`	Advertised API address for this node.
`user_shards`	`8`	Number of user-data shards.
`shared_shards`	`1`	Number of shared-data shards.
`heartbeat_interval_ms`	`250`	Raft leader heartbeat interval.
`election_timeout_ms`	`(500, 1000)`	Min/max election timeout range. Min must exceed heartbeat.
`snapshot_policy`	`"LogsSinceLast(1000)"`	Snapshot policy. Use `LogsSinceLast(N)` or `Never`.
`max_snapshots_to_keep`	`3`	Snapshot retention count. `0` keeps all snapshots.
`replication_timeout_ms`	`5000`	Timeout for learner catch-up and replication progress.
`reconnect_interval_ms`	`3000`	Delay between reconnect attempts to unreachable peers.
`peer_wait_max_retries`	unset	Optional cap on peer-startup readiness retries.
`peer_wait_initial_delay_ms`	unset	Optional initial delay between peer readiness checks.
`peer_wait_max_delay_ms`	unset	Optional backoff cap for peer readiness checks.

`[[cluster.peers]]`

Key	Default	Description
`node_id`	required	Peer node ID.
`rpc_addr`	required	Peer RPC address.
`api_addr`	required	Peer API address.
`rpc_server_name`	unset	Optional TLS server-name override for SNI/hostname verification.

Total Raft groups = 3 fixed groups (system metadata, user metadata, jobs) + user_shards + shared_shards.

Validation highlights:

node_id must be greater than 0
election_timeout_ms.0 must be greater than heartbeat_interval_ms
election_timeout_ms.1 must be greater than election_timeout_ms.0
user_shards and shared_shards must be greater than 0
non-localhost multi-node clusters require rpc_tls.enabled = true

Advanced Configuration

Before You Start

Loading Order

Environment Override Reference

Server, Logging, and Storage

Topics, Auth, Security, and WebSockets

Cluster and RPC TLS

Runtime-Only Environment Variables

Full server.toml Reference

Top-Level Keys

[server]

[storage]

[storage.remote_timeouts]

[storage.rocksdb]

[storage.rocksdb.cf_profiles.system_meta]

[storage.rocksdb.cf_profiles.system_index]

[storage.rocksdb.cf_profiles.hot_data]

[storage.rocksdb.cf_profiles.hot_index]

[storage.rocksdb.cf_profiles.raft]

[datafusion]

[flush]

[flush.compaction]

[retention]

[stream]

[manifest_cache]

[limits]

[logging]

[logging.otlp]

[performance]

[rate_limit]

[security]

[security.cors]

[websocket]

[auth] or [authentication]

[auth.local]

[auth.oidc]

[user_management]

[files]

[shutdown.flush]

[jobs]

[execution]

[topics]

[rpc_tls]

[cluster]

[[cluster.peers]]