Configuration reference

Every CLI flag and environment variable, with defaults. For the precedence rules (env var > control-plane setting > default) and which knobs are live vs. restart-only, see the Configuration model.

CLI

Global flags:

Flag	Default	Description
--data-dir <path>	./data	Local data directory: partitions, single-node control plane, generated keys.
--verbose	off	Extra diagnostics during serve.

serve:

Flag	Default	Description
--port <n>	7300	HTTP/MCP listen port.
--host <addr>	127.0.0.1	Bind address (0.0.0.0 for all interfaces).
--shared-store <uri>	—	FS/NFS path or s3://bucket/prefix for multi-node/DR.
--frontend-dir <path>	—	Built SPA directory; must contain index.html.
--syslog-port <n>	—	Override syslog UDP+TCP port; 0 disables. (Also HELIOS_SYSLOG_PORT.)

Admin bootstrap

Applied at startup. See First steps.

Variable	Default	Description
HELIOS_ADMIN_USER	admin	First-run admin username.
HELIOS_ADMIN_PASSWORD	—	First-run admin password. If unset (and no users), the setup wizard runs instead.
HELIOS_ADMIN_EMAIL	<user>@localhost	First-run admin email.
HELIOS_ADMIN_RESET	—	Truthy + a password resets that admin's password (and revokes sessions) every boot.

Secrets & control plane

Variable	Default	Description
HELIOS_CONTROL_KEY_PATH	./secret-control.json	Control-plane encryption key file (auto-created). Keep outside --data-dir.
HELIOS_JWT_SECRET_PATH	./secret-jwt.json	JWT signing-secret file (auto-created). Keep outside --data-dir.
HELIOS_CONTROL_ENCRYPTION	on	AES-256-GCM encryption at rest. 0/off/false/no disables.
HELIOS_CONTROL_CACHE_TTL_SECS	10	TTL for the hot single-document read cache; 0 disables.

See Secrets & encryption.

Storage engine (startup-fixed)

Variable	Default	Description
HELIOS_BLOCK_COMPRESSION	zstd	Block compression. off/none/0/false writes uncompressed.
HELIOS_BLOCK_QUEUE_CAP	100000	Ingest queue depth; full queue → backpressure (429 on shims).
HELIOS_BLOCK_FLUSH_CONCURRENCY	2	Concurrent block flushes (caps buffered memory).

Live tunables

Editable in Admin → General (env var, if set, wins and locks the field). See Performance tuning.

Variable	Default	Live?	Description
HELIOS_BLOCK_COMPACT_SECS	30	yes	Compaction walk interval.
HELIOS_BLOCK_TARGET_MB	64	yes	Compaction target block size.
HELIOS_BLOCK_MIN_COMPACT_MB	5	yes	Compaction floor.
HELIOS_BLOCK_MAX_SMALL_BLOCKS	100	yes	Small-block count that waives the floor.
HELIOS_BLOCK_FLUSH_ROWS	50000	yes	Buffered-ingest row flush threshold.
HELIOS_BLOCK_FLUSH_SECS	5	yes	Buffered-ingest time flush interval.
HELIOS_BLOCK_SYNC_SECS	10	yes	Shared-store sync interval (with --shared-store).
HELIOS_RETENTION_SWEEP_SECS	3600	yes	Retention sweep interval.
HELIOS_AGG_MAX_PARTITIONS	96	yes	Partitions aggregated exactly before stride-sampling.
HELIOS_QUERY_CACHE_MB	1024	yes	Per-block match cache; 0 disables.
HELIOS_QUERY_THREADS	4	no	Query fan-out threads. Restart to apply.
HELIOS_AUTH_TOKEN_TTL_HOURS	168	yes	Session (JWT) lifetime in hours (7 days).

Retention

Variable	Default	Description
HELIOS_RETENTION_DEFAULT_DAYS	— (keep forever)	Global default retention in days; wins over the control setting. 0/blank = keep forever. Per-env overrides in Admin → Environments.

Syslog

Variable	Default	Description
HELIOS_SYSLOG_PORT	—	Override the control-plane syslog UDP+TCP port; 0 disables the listener. (= --syslog-port.)

The rest of syslog (enable, bind, ports, routes) is configured in the control plane — see Syslog.

AWS / S3 (shared store)

When --shared-store is an s3:// URL:

Variable	Default	Description
AWS_REGION	— (required)	S3 region. Required (IMDS is not used). May come from an AWS profile's region.

Credentials use the standard AWS provider chain (env vars, shared credentials, SSO, instance roles, …). See Multi-node & shared store.

Logging

Variable	Default	Description
RUST_LOG	info,hyper=warn	Log verbosity filter (standard tracing syntax). Logs go to stderr.