#Mental Model

#Builds must be repeatable

Think of a build as a recipe you can hand to someone else — including future you. Its saved manifest is the source of truth: re-running it later should produce an equivalent module.

That matters because dependencies change: packages are patched, base images move, checksums expire, and configuration drifts. A template VM with undocumented manual changes is difficult to rebuild when you need it most.

Avoid manual steps. Prefer shell and file provisioners. Use handbuild only when automation is not possible. Document every click, keystroke, and value.
Pin dependencies where needed. Pin ISO checksums, use dated cloud-image URLs instead of latest, and pin package versions when a change could break the build.
Keep build inputs in the manifest. Add scripts, drivers, certificates, and install files to Files, or retrieve them from stable URLs. Do not rely on undocumented uploads or setup.
Make provisioners idempotent. Retrying a step should not fail or leave the VM in a different state. See Best practices.
Clean up before snapshotting. Remove transient files and state so each template is consistent.

When a build breaks, update the manifest and run it again. You should never have to reverse-engineer an old VM to remember how it was made.

#Modules, builds, and clones

Module: One or more VMs built, snapshotted, and cloned together. Most modules have one VM; a client/server pair is one example of a multi-VM module.
Build: The configuration that produces a module's template VMs.
Clone: A running copy of an entire module. It includes the same disks, network topology, and VM relationships as the templates.

#What a build contains

A build defines:

The VMs in the module.
Each VM's source disk: a cloud image, an ISO with a blank disk, or another build's output.
Optional build files, such as scripts, certificates, unattend files, and drivers.
Ordered provisioners for each VM, such as shell commands, file uploads, and reboots.
An optional network topology shared by the module's VMs.

When you run a build, the system boots the VMs, runs their provisioners, shuts them down, and snapshots their disks.

flowchart LR A[Build<br/>configuration] --> B[Boot VMs from source] B --> C[Run provisioners<br/>over SSH] C --> D[Shut down VMs] D --> E[Snapshot each disk] E --> F[Template module:<br/>halted VMs ready to clone]

A successful build produces halted template VMs. Cloning starts a running copy of every VM in the module. You are done when the build succeeds and you can run it again with equivalent results.