Rudder Virt

#Building VM Images

This guide is for people who build modules. A module is one or more VMs built, snapshotted, and cloned as a group. You define their source images, provisioning, networking, ISOs, and files; Rudder Virt turns that definition into a reusable template.

The editor has two modes, and you can switch between them at any time:

  • Visual: a form with sections for files, networking, and each VM (source, resources, communicator, network interfaces, provisioners). Use this when you want guided editing, or when you only need the common fields.
  • YAML: the underlying manifest as raw text. Use this for advanced fields the form does not expose, for diffing changes, or when copying a recipe from this guide.

The two modes round-trip through the same manifest, so switching does not lose data. Switching from Visual to YAML may reformat the document and drop comments, since serialization is regenerated from the form state.

This guide explains what belongs in a build. For implementation details, see Under the hood.

  • Mental Model — 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.
  • Building with AI agents — Rudder Virt exposes a Model Context Protocol (MCP) server so AI agents and other automation can create and maintain modules without using the web editor. An agent connected to the server can list and read modules, write module details, manifests, and rubrics, run and promote builds, review grades, and see and drive a VM's graphical console. It can also read this documentation, so it can learn the aileron manifest format before writing one.
  • Concepts — These pages explain one part of a build at a time. Each covers the concept, its visual-editor controls, and the matching YAML.
  • Recipes — These complete examples cover common build patterns.
  • Best Practices — Reboot any time a step changes something that needs a clean process tree:
  • Troubleshooting — Network resources couldn't be created. Check that:
  • Reference — The YAML field reference. The visual editor exposes the most common fields under the same names (see each concept page); the tables below list every field, including the ones reachable only by editing the YAML.
  • Under the Hood — You don't need any of this to write a build. It's here so the names you'll run into in upstream documentation, log output, and community forums make sense.