nixos-build-vms(8)

🌈 nixos-build-vms(8) — the manual page, but make it make sense ✨

okay bestie, welcome to section 8 of the System Manager's Manual, and buckle up because this one's actually kind of cool 💅

🎀 NAME 🎀

nixos-build-vms — build a whole network of virtual machines from a network of NixOS configurations 🖥️✨🖥️

---

✨ SYNOPSIS ✨

nixos-build-vms [--show-trace] [--no-out-link] [--help]
                [--option name value] network.nix

that's it. that's the whole vibe check. one file in, a fake little internet out 🦋

---

💖 DESCRIPTION 💖

so basically, this command builds a network of QEMU-KVM virtual machines from a single Nix expression that describes a network of NixOS machines. yes, a whole network. from one file. main character energy fr fr 👑

once it's built, you can start the whole virtual network by running the bin/run-vms shell script that this command generates. it literally hands you the keys 🫶

and by default it produces a result symlink that points at the generated virtual network, so you can find your little baby again later. cute.

a network Nix expression looks like this, bestie — memorize the shape, not the content:

{
  test1 = {pkgs, config, ...}:
    {
      services.openssh.enable = true;
      nixpkgs.localSystem.system = "i686-linux";
      deployment.targetHost = "test1.example.net";

      # Other NixOS options
    };

  test2 = {pkgs, config, ...}:
    {
      services.openssh.enable = true;
      services.httpd.enable = true;
      environment.systemPackages = [ pkgs.lynx ];
      nixpkgs.localSystem.system = "x86_64-linux";
      deployment.targetHost = "test2.example.net";

      # Other NixOS options
    };
}

okay so breaking that down 🌸 — every attribute in the expression is one machine in the network (think test1 and test2 up there), and each one refers to a function that defines a NixOS configuration.

inside each NixOS configuration, two attributes are special and you should lowkey pay attention:

• deployment.targetHost — tells you the address (domain name or IP address) of the system, and ssh uses it to perform remote deployment operations. it's giving "where do I knock" 🚪
• nixpkgs.localSystem.system — lets you pick an architecture for the target machine, like 'i686-linux', which builds a 32-bit NixOS configuration. very demure, very cross-compiled 🧚

and if you just... don't include that nixpkgs.localSystem.system property at all? no stress — it'll build the configuration for the same architecture as the host system. default behavior, slay 💅

---

🔥 OPTIONS 🔥

• --show-trace — shows a trace of the output. when things go sideways, this is your receipts 😭
• --no-out-link — do not create a result symlink. no little shortcut left behind, we love a clean exit.
• -h, --help — shows the usage of this command to the user. the classic "help me help you" 🫶
• --option name value — set the Nix configuration option name to value. this overrides settings in the Nix configuration file (see nix.conf(5)). yes, overrides. it wins. periodt 👑

---

💜 AUTHORS 💜

Eelco Dolstra and the Nixpkgs/NixOS contributors — absolute icons, no cap 🏆

---

nerdiest footnote ever but: this page lives on Debian, dated January 1, 1980 (yes really, the epoch birthday 🎂), and it's page nixos-build-vms(8) of the System Manager's Manual. mwah, go build a tiny internet 💋🌈