Configuration precedence#

A value reaching a running swarm can come from four places. Knowing which one won is the difference between a five-minute fix and an afternoon.

The chain#

Highest priority first:

  1. CLI arguments and the YAML config — what you wrote for this swarm

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

  3. Built-in defaults — the values in the Pydantic models

  4. Environment variables — a separate axis; see below

Any field you omit inherits from the next level down, which is why configs can stay to three or four lines.

domyn-swarm init defaults#

Records the values that are the same for every swarm on your cluster, so they stop being repeated in every config:

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.

Re-run it whenever the cluster changes; --force overwrites an existing file. Individual values can still be overridden per swarm — switch the partition, qos or nginx_image for one deployment while everything else keeps the recorded defaults.

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#

This is the part that surprises people, and it is visible in the generated Configuration reference.

Fields like backend.partition, backend.account and backend.qos are shown as computed rather than required, because their default is a factory that reads defaults.yaml. But that factory has no fallback: if the key is missing or empty in defaults.yaml, and you did not supply it in your YAML, it raises

Missing required configuration key: slurm.partition

So computed means “resolved from defaults.yaml, or an error” — not “safe to omit”. A field is genuinely safe to omit only when its description names a concrete default or a formula.

This is also why the same config file works for one colleague and fails for another: their defaults.yaml differs, and nothing in the config file records the 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 config fields, and they do not sit in the chain above. They configure the process: where state lives, log verbosity, API tokens. Full list: Environment variables.

Two of them do reach into swarm configuration, which is worth knowing:

  • DOMYN_SWARM_HOME supplies the default for home_directory, so it moves where state, logs and checkpoints are written

  • DOMYN_SWARM_DEFAULTS selects which defaults.yaml is read, and therefore changes level 2 of the chain wholesale

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 key it resolves and the fallback it considered, which is usually enough to see whether a value came from your YAML, from defaults.yaml, or from a built-in default.