Configuration model

HeliosLogs is configured in three layers with a clear precedence. Understanding the model means you'll never be surprised by which value "wins." The exhaustive list of every flag and variable lives in the Configuration reference; this page explains how they combine.

Three layers, one precedence

environment variable > control-plane setting > built-in default

1. Environment variable — set at process start. When present, it wins and locks the corresponding field in the admin UI (you can't override an operator's env choice from the browser).
2. Control-plane setting — edited in Admin → General, stored in the control plane, and shared across all nodes in a cluster.
3. Built-in default — used when neither of the above is set.

Invalid or out-of-range values fall through to the next layer. For example, a tunable below its minimum is treated as unset.

Startup-fixed vs. live-tunable

Settings fall into two groups:

• Startup-fixed — read once when the process starts. Changing them requires a restart. These are CLI flags (--port, --shared-store, …) and a set of environment variables (the secrets, encryption toggle, admin bootstrap, block compression, ingest queue sizing, syslog port).
• Live-tunable — the "server tunables" editable in Admin → General. Editing one applies within seconds — no restart — unless an env var locks it. The one exception is query threads, which is restart-only (the thread pool is built once at startup).

The live tunables are:

Tunable	Env var	Default
Compaction interval	HELIOS_BLOCK_COMPACT_SECS	30 s
Compaction target size	HELIOS_BLOCK_TARGET_MB	64 MB
Compaction floor	HELIOS_BLOCK_MIN_COMPACT_MB	5 MB
Small-block waiver count	HELIOS_BLOCK_MAX_SMALL_BLOCKS	100
Ingest flush rows	HELIOS_BLOCK_FLUSH_ROWS	50 000
Ingest flush interval	HELIOS_BLOCK_FLUSH_SECS	5 s
Shared-store sync interval	HELIOS_BLOCK_SYNC_SECS	10 s
Retention sweep interval	HELIOS_RETENTION_SWEEP_SECS	3600 s
Aggregation partition budget	HELIOS_AGG_MAX_PARTITIONS	96
Query result cache	HELIOS_QUERY_CACHE_MB	1024 MB (0 disables)
Query threads (restart-only)	HELIOS_QUERY_THREADS	4
Session token lifetime	HELIOS_AUTH_TOKEN_TTL_HOURS	168 h (7 days)

See Performance tuning for guidance on the storage/query knobs.

Where to set things

Configuration	Where
Bind address, port, data dir, shared store, frontend dir	CLI flags to serve
Secrets, encryption, admin bootstrap, control cache	Environment variables only
Server tunables (above)	Env var or Admin → General
Retention default	HELIOS_RETENTION_DEFAULT_DAYS env, or Admin → General; per-env override under Admin → Environments
Theme defaults, appearance	Admin → General

Inspecting the effective configuration

Admin → General shows two things:

• A read-only runtime config view of startup-fixed settings — including whether each value came from an env var or a default, and the active crypto provider (standard vs. FIPS).
• The server tunables editor, where each row shows the effective value, the configured (control-plane) value, and any env override that is locking it.

This is the quickest way to answer "what is this node actually running with?"

A baseline for small production

A reasonable starting point for a single production node:

# Secrets on persistent, backed-up paths (not under --data-dir)
HELIOS_CONTROL_KEY_PATH=/etc/helios/secret-control.json
HELIOS_JWT_SECRET_PATH=/etc/helios/secret-jwt.json

# Bootstrap an admin on first boot
HELIOS_ADMIN_EMAIL=ops@example.com
HELIOS_ADMIN_PASSWORD=...        # use a real secret manager

# Keep disk bounded
HELIOS_RETENTION_DEFAULT_DAYS=30

# Shorter sessions if desired (default is 7 days)
HELIOS_AUTH_TOKEN_TTL_HOURS=24

Leave the storage/query tunables at their defaults until you have a reason to change them.