Building a VyOS Libvirt Box

VyOS is supported by the netlab libvirt package command. The public vyos/current Vagrant box is no longer maintained; instead, build a local Vagrant box from a recent VyOS ISO image.

Warning

Building a VyOS Libvirt box is not straightforward, and this recipe is maintained on a best-effort basis. Use the VyOS containerlab image whenever possible.

The default Vagrant box name used by netlab is netlab/vyos. When the netlab libvirt package command asks for a box version, use the VyOS image version or build ID, for example 2026.09.01-0034-rolling.

The old vyos/current Vagrant box is no longer used as the default image. Set the defaults.devices.vyos.libvirt.image default setting to vyos/current to use it (more details).

Download a VyOS ISO Image

You can use any recent VyOS ISO image that supports the configuration syntax used by netlab. The usual public choices are:

  • Download the latest VyOS rolling/nightly ISO image from the VyOS rolling release builds page.

  • Download a VyOS Stream ISO image from the VyOS download page if you prefer a less volatile public preview build.

VyOS publishes .minisig files for public images. Use the verification instructions on the VyOS download page to validate the ISO before installing it.

Build the Vagrant Box

Execute netlab libvirt package vyos iso-image-name and follow the instructions.

Warning

If you’re using a netlab release older than 1.8.2, or if you’re using a Linux distribution other than Ubuntu, please read the box-building caveats first.

The box-building process has two stages:

  • The VM with an empty disk is booted from the ISO image

  • You start the VyOS installation process and reboot the VM

  • The VM is booted from the virtual disk

  • You mount the secondary CD-ROM and execute the final installation script

Installing VyOS from ISO image
==============================

* Wait for the VM to boot
* Log in using `vyos` as username and password
* Run `install image`
* Install VyOS on `/dev/vda`. Answer 'Y' or accept defaults for all questions.
  Set password to `vyos`
* Reboot the VM with `reboot`

Initial configuration
============================

* Wait for the VM to boot
* Log in using `vyos` as username and password
* Mount the secondary CD-ROM with `sudo mount /dev/sr1 /mnt`
* Execute `bash /mnt/install.sh`

The installation script configures the management VRF, installs pre-boot script,
and powers off the VM

Behind the Scenes

The installation script copies netsim firstboot script into the VM as /config/scripts/vyos-preconfig-bootup.script. When the lab VM boots from the Vagrant box, VyOS runs that persistent preconfig script after initial interface name resolution, but before interface rescan and before the boot configuration is loaded. The script finds the netlab management interface by its ca:fe:* MAC address and netlab data interfaces by their ca:f0:* MAC addresses, writes matching hw-id bindings into the boot configuration, marks itself done, and triggers a reboot. On the next boot, VyOS uses those saved hw-id bindings to rename the interfaces before loading the configuration.

Notes on Using the VyOS Box

The default Vagrant box name used by netlab is netlab/vyos. When netlab libvirt package asks for a box version, use the VyOS image version or build ID, for example 2026.09.01-0034-rolling.