Skip to content

Images and templates

Updated

A Linux VM boots from a cloud image: a prepared Linux disk image with cloud-init inside. Virtainer Free keeps a local cache of those images and copies from the cache every time you create a VM. Windows VMs use prepared Windows Server images; see Windows guests.

The Images page under Virtual machines (/vm/images) is a catalogue of what this host can boot, shaped like a registry: one card per operating system. A card is a directory rather than a single release. The Debian card states Debian 13 and Debian 12 as separate rows.

Each row leads with the newest build upstream has published for that major version and carries a Download button for it, or a check when this host already holds that exact build. Beside the row the card states how many builds of that version exist and how many this host holds, for example 2 builds · 1 on disk, and the card header totals the same facts for the whole operating system.

When a version holds more than one build, All N builds appears on the card and opens that operating system’s own page (/vm/images/:distro): one page per distro, a section per major version, and every build listed newest first with its file name, size, date, and a short checksum. Each build carries a Download button, or an On disk check if the host holds it, and the newest build of each version is marked Newest. That page reads and downloads. Deletion never happens there, so a destructive click cannot sit one mis-select away from a Download button.

Search matches distro, version, release, or file name. The tags beside it narrow to one operating system, or to On disk for what this host holds. Tags carry no counts: the only number an operator acts on is how much the host is holding, and the footprint card states it once.

There are four ways to add an image:

  • From the catalogue. Use the Download button on a version row to fetch that build. The host downloads it once and verifies its checksum.
  • From a URL or an upload. Add Image takes a qcow2 image you already have, as an uploaded file or a URL the host pulls.
  • By building a Windows image. Build Windows image on this page installs Windows Server from an ISO you provide, unattended on the host, and publishes the result as an image. See below.
  • From a machine you already built. Turn a stopped VM’s root disk into a reusable image. See below.

Once an image is cached, creating a VM from it does not touch the network.

When an image arrives, the host checks its operating system, boot compatibility and first-boot capabilities without starting a VM. Manage images shows the operating system it identifies. Those checks let the create form offer compatible login options, Console auto-login and first-boot accounts, and choose a safe NIC offloads default.

  • BIOS-only images are refused. VMs here boot with UEFI firmware, so an image with a BIOS boot path and no EFI system partition could never start. It is rejected as it arrives, with a message saying so; most distributions publish a UEFI build alongside.
  • An image the host cannot read is still accepted. Encrypted or LVM root filesystems, for example, are not read. The image can still boot; its first-boot setup uses standard Linux defaults. Verify access and first-boot configuration on a test VM before relying on an unreadable custom image.
  • Images cached before the host read images are read the first time they are listed or used to create a VM.

Downloads happen on the host, not in your browser, so the page reports on them directly. Start one and the button on that row turns into a progress bar, with the current rate and an estimate of the time remaining. When it finishes, the downloaded release takes its place.

The rate is the number worth watching. It is what tells a slow mirror apart from a stalled one. If the server does not report a total size, you get bytes downloaded and the rate without an invented percentage.

Windows images are not downloaded from the catalogue. Choose Build Windows image in the header of the Images page and the host builds one from a Windows Server 2019, 2022 or 2025 ISO that you upload or give a URL for, evaluation ISOs included. The dialog has three steps, Installation ISO, Edition and options and Confirm; Start build then hands over to Operations, where the build appears as Build Windows image and runs without further input. The host verifies the finished image before it is published, and a build that does not verify is not added.

The result appears in the list like any other image and creates VMs without further preparation. The ISO requirements, the options, the build stages and what to do when a build fails are in Windows guests.

A VM you have configured by hand can become the starting point for the next ones. Stop it completely, then choose More → Create image on its page and give the image a name. While the machine is running the menu item is still listed, greyed out, with the reason appended: “Create image — stop the VM completely first”. The export runs on the host; follow it in Operations, and use Recheck if Virtainer Free restarts while it is running. The result appears on the Custom card of the VM images page and creates new VMs like any other image.

Only the root disk travels. The machine’s CPU and memory, its NICs, its data volumes, and its snapshots stay behind, though any files those features left on the root disk are copied along with everything else. To reproduce a whole machine rather than a starting point, use a transfer package or a backup.

Each VM’s disk is booked against the pool at the size the disk was created with, which is the larger of the size you asked for and the image’s own capacity, and it shares the image’s blocks on a copy-on-write pool, so the capacity card counts those shared blocks once, under Base images, rather than once per machine. Plan pool capacity by the disks you hand out and what the machines write, not by the number of distinct images.

A template is a saved set of create-form settings: the image, the first-boot configuration, the shape of the machine, and the options you would otherwise retype. A VM template pins one specific image build rather than “the latest of a distribution”, so a template used a month apart builds the same system. A field you leave empty (or Not set) is not preset, and the create form uses its own default for it. The password, MAC address and PCI devices stay out of a template. Custom user-data can contain secrets and is stored hidden; keep your own copy. One Templates page holds the classic VM templates and another holds the AppVM ones: Templates under Virtual machines (/vm/templates) and Templates under AppVMs (/appvm/templates), each listing only its own kind.

  1. Open Templates under Virtual machines or under AppVMs and create one.
  2. Fill in the settings you want to reuse.
  3. Pick that template when you create a machine, or leave the picker on No template, and adjust anything per machine.

A template is applied at creation time. It fills the form in, and editing the template later does not reach back into machines that were already created from it.

The Batch row under Advanced on the create form works with or without a template. How many sets the count (up to 256). Number from sets where the numbering starts, so running the same settings again later appends to an existing group instead of colliding with the names you already used; with static addressing, IP step controls the spacing between them. Neither is shown while the count is one, and a preview lists the names and addresses that will be used.

Put an {n} token in the hostname to say where the number goes (web-{n}, or web-{n:03} for zero padding). A hostname without a token gets -{n} appended, and an empty hostname leaves each VM to be named from its own id. With static addressing, the starting address must be given as CIDR, and it is checked before anything is created.

AppVMs can be created several at a time too. They do not step static addresses, and a blank hostname is fine there because each machine derives a distinct name of its own.

A template is a small JSON document, and the console treats it as one. Each template row can be exported, which downloads a file named after the template with a .template.json suffix, and the Templates page has an Import button that takes such a file back in. The empty state offers the same thing as Import a file.

A template containing hidden custom user-data cannot be exported as JSON, since the file would omit that document. Templates without it can still be exported.

That is the practical way to keep a set of machine shapes you have already tuned: export them from the host where you built them, and import them on the next one. A template carries create-form settings and nothing else, so importing one creates no disks, copies no image, and starts no machine. It fills the form on a host that has the images it names.

If the form does not cover what you need, a VM template can carry your own #cloud-config document, which is appended to the configuration Virtainer Free generates. Use it for the parts that are genuinely yours; let the form handle hostname, users, and networking so the console and the guest agree on what was set.

After saving, the document is never returned by read APIs or filled back into an editor. The Cloud-Init panel shows Set (hidden). Template editing and reinstall offer Keep, Replace, or Remove. Keep preserves it within the same OS family; switching between Linux and Windows does not carry the document over. Removing or replacing it during a Linux reinstall must still leave a valid login method, or the request is refused before the disk is replaced.