Reference
Defaults
Settings that are yours or your team's rather than the spec's: the image table, the Vagrant provider, each cloud's region, in layers with a file, the environment and -s key=value.
A spec says what an environment is. Some choices belong to whoever runs it: which Vagrant provider, which cloud region, which boxes stand for an OS, which image supplies the access machine. Those are defaults, set once, in layers. The last layer wins, leaf by leaf, so a file that sets one region leaves the others alone.
| Layer | Where | For |
|---|---|---|
| 1. Built in | Isoloom itself | the image table, each cloud's region |
| 2. Your file | ~/.isoloom/defaults.yml ($ISOLOOM_HOME/defaults.yml) | your own preferences on this machine |
| 3. The project's file | isoloom.defaults.yml, next to isoloom.yml | the team's choices, committed |
| 4. Environment | ISOLOOM_<KEY>, __ for a dot: ISOLOOM_CLOUD__AWS__REGION=eu-west-1 | CI, scripts |
| 5. Command line | -s defaults.<key>=<value> on generate, run, test, check, inspect | one run |
# isoloom.defaults.yml
images:
os:
debian-12: { vagrant: my-org/debian-12, vagrant_version: "1.2.0" }
access:
docker: kalilinux/kali-rolling
vm: kali
vagrant:
provider: libvirt
cloud:
aws: { region: eu-west-1 }
azure: { region: westeurope }
| Key | Effect |
|---|---|
images.os.<name> | The image for an OS name, per target (vagrant, vagrant_version, winrm): what generate --images took, and still takes, as one more layer. |
images.access | The access machine when the spec leaves it to the runner: docker (a container image) and vm (an OS name). |
vagrant.provider | isoloom run vagrant passes --provider. |
cloud.<cloud>.region | The region the generated Terraform module defaults to (aws, azure, gcp, digitalocean, linode, oci). |
Unknown keys are errors, with the layer that holds them.
What they change
Images and regions change the generated files, so generate, check, run and test all
read the same layers: a project file is the right place for what the team shares, since CI has it
too. A region or image set in your own file or environment changes .isoloom/ on your machine
only; isoloom check then reports the difference, as it should. vagrant.provider only changes
how run calls Vagrant.
Overriding the spec itself
The same -s without the defaults. prefix changes the spec for one command, before it is
parsed:
isoloom run vagrant -s machines.web.vm.os=ubuntu-24.04
isoloom generate -s networks.lab.internet=false -s machines.cache.resources.memory_mb=2048
Values read as YAML (3, true, text). The file on disk is untouched.
isoloom defaults
$ isoloom defaults
cloud.aws.region eu-west-1 project file /Users/me/lab/isoloom.defaults.yml
cloud.azure.region swedencentral built in
cloud.gcp.region europe-west9 built in
vagrant.provider libvirt user file /Users/me/.isoloom/defaults.yml
Every value in effect, with the layer that set it. --system prints the built-in layer alone,
--json is for programs.