Configuration

Configuration that outlives one command lives in a small set of TOML files inside one configuration directory. This is deliberately separate from --data-dir, which holds state, not settings.

Where the configuration directory is

Lookups walk these locations in order and the first file found wins:

Precedence Location

1. --config-dir PATH

Exactly that directory, nothing else is searched.

2. User config dir

Linux: ~/.config/waratah (or $XDG_CONFIG_HOME/waratah) · macOS: ~/Library/Application Support/waratah · Windows: %APPDATA%\waratah

3. System config dir

Linux: /etc/waratah · macOS: /Library/Application Support/waratah · Windows: %PROGRAMDATA%\waratah

Two files live there today: cluster.toml (where the cluster’s processes are) and notebooks.toml (the Jupyter service).

cluster.toml — the address table

waratah start reads this to find the five processes it orchestrates. The whole file for a single-machine cluster:

compute = "127.0.0.1:7005"

[hexastore]
s = "127.0.0.1:7001"
p = "127.0.0.1:7002"
o = "127.0.0.1:7003"

[registry]
0 = "127.0.0.1:7004"
Key Meaning

compute

Address of the compute node’s internal gRPC listener.

[hexastore] s / p / o

Addresses of the three storage partitions.

[registry] <number>

Addresses of string-registry shards, keyed by numeric node id.

When no cluster.toml is found, the built-in local defaults are used — exactly the addresses above: partitions on 127.0.0.1:7001–7003, registry on 7004, compute on 7005. A waratah start with no configuration therefore matches a default cluster.toml byte for byte.

waratah start --config PATH reads the table from an explicit file instead, ignoring the search path. The file also accepts a self_id string and a list (each entry an id and a grpc address) for multi-compute setups — the single-compute form above is the one-machine shape.

notebooks.toml — the Jupyter service

One flat table; unknown keys are ignored so newer engines keep reading older files. Every value can instead be given as a waratah start flag, and flags win: the merge order is command-line flag over notebooks.toml value over built-in default.

Key Flag Meaning

enabled

--with-notebooks

Turn the notebook service on (true / false).

dir

--notebooks-dir

Root directory holding the notebooks. Default {data_dir}/notebooks (or ./notebooks with the memory backend).

python

--notebooks-python

Python interpreter for the sidecar. Default: a pinned virtual environment created automatically on first start.

bind

--notebooks-bind

Loopback bind for the sidecar; 127.0.0.1:0 lets the engine pick the port (the default).

token

--notebooks-token

Jupyter authentication token; minted automatically at startup when unset.

cull_idle_secs

--notebooks-cull-idle-secs

Shut down kernels idle longer than this many seconds. Default 3600.

What the service does with these values is covered in Jupyter Notebooks.