Configuration precedence#

A swarm value can come from four sources. The source determines which value the swarm uses.

The chain#

Highest priority first:

  1. CLI arguments and the YAML configuration for the swarm

  2. defaults.yaml, written by domyn-swarm init defaults

  3. Built-in defaults from the Pydantic models

  4. Environment variables, which use separate precedence rules

Any field you omit inherits from the next level down. A configuration can therefore contain only three or four lines.

domyn-swarm init defaults#

This command records the values that are the same for every swarm on your cluster. You do not need to repeat these values in each configuration:

domyn-swarm init defaults

It prompts for Slurm partition, account and QoS, the endpoint’s Nginx image and port, the polling interval, and optionally the Lepton workspace and images. The answers are written to ~/.domyn_swarm/defaults.yaml, or to -o/--output.

Run the command again after the cluster configuration changes. The --force flag overwrites an existing file. A swarm configuration can override individual values such as partition, qos, or nginx_image.

How defaults.yaml is found#

The lookup, in order:

  1. Settings.defaults_file, which the DOMYN_SWARM_DEFAULTS environment variable sets

  2. otherwise the built-in candidate locations, of which ~/.domyn_swarm/defaults.yaml is the usual one

The file is loaded once and cached for the process.

“Computed” defaults that are actually required#

The generated Configuration reference marks some fields as computed.

Fields such as backend.partition, backend.account and backend.qos are shown as computed. Their default is a factory that reads defaults.yaml. The factory has no fallback. It raises this error if the key is empty or absent from both defaults.yaml and the swarm YAML:

Missing required configuration key: slurm.partition

Here, computed means that the field resolves from defaults.yaml or raises an error. A field is optional only when its description gives a default or formula.

The same swarm configuration can behave differently with another defaults.yaml file. The swarm configuration does not record this dependency.

Environment variables are a different axis#

Settings reads environment variables prefixed DOMYN_SWARM_, plus .env in the working directory and ~/.domyn_swarm/.env. Some fields carry explicit aliases that drop the prefix, such as VLLM_API_KEY.

These are not swarm configuration fields, so they are not part of the chain above. They configure the process, including state storage, log verbosity, and API tokens. See Environment variables for the full list.

Two environment variables affect swarm configuration:

  • DOMYN_SWARM_HOME supplies the default for home_directory. It changes where state, logs and checkpoints are written.

  • DOMYN_SWARM_DEFAULTS selects the defaults.yaml file. It changes the second level of the precedence chain.

Both are read when the value is first resolved, so exporting them after a process has started has no effect on it.

Debugging where a value came from#

Set DOMYN_SWARM_LOG_LEVEL=DEBUG. The defaults loader logs each resolved key and the fallback that it considered. The log identifies values from the swarm YAML, defaults.yaml, and built-in defaults.