CloudSOE publishes base boxes for the libvirt and VirtualBox providers. They are hosted on boxes.cloudsoe.com, not on Vagrant Cloud, so the only difference from a box you have used before is one extra line: the URL of the box metadata.

What you’ll need

  • A current Vagrant release (2.4 or newer is recommended)
  • One provider:
    • VirtualBox 7.x, or
    • libvirt/KVM with the vagrant-libvirt plugin (vagrant plugin install vagrant-libvirt)
  • An x86-64 (amd64) host. The boxes are built for amd64 only.

Step 1: Pick a box

BoxLatest versionReleasedProvidersArchVerifyUse
cloudsoe/debian-12Debian12202611.15.02026-11-15libvirtVirtualBoxamd64SHA-256How to use →
cloudsoe/debian-13Debian13202611.15.02026-11-15libvirtVirtualBoxamd64SHA-256How to use →
cloudsoe/ubuntu-24.04Ubuntu24.04202611.14.02026-11-14libvirtVirtualBoxamd64SHA-256How to use →
cloudsoe/ubuntu-26.04Ubuntu26.04202611.15.02026-11-15libvirtVirtualBoxamd64SHA-256How to use →

Step 2: Write the Vagrantfile

Vagrant.configure("2") do |config|
  config.vm.box     = "cloudsoe/ubuntu-24.04"
  config.vm.box_url = "https://boxes.cloudsoe.com/cloudsoe/ubuntu-24.04.json"
end

box_url points at a small JSON file that lists every version of the box, with a download URL and SHA-256 checksum per provider. Vagrant picks the newest version for your provider, downloads it and checks the checksum before importing.

To create the same file from the command line:

vagrant init cloudsoe/ubuntu-24.04 https://boxes.cloudsoe.com/cloudsoe/ubuntu-24.04.json

vagrant init cloudsoe/ubuntu-24.04 on its own does not work. Without the URL, Vagrant looks the name up on Vagrant Cloud.

Step 3: Start the machine

vagrant up --provider libvirt      # or: --provider virtualbox
vagrant ssh

The first vagrant up downloads the box, which is 600 to 800 MB depending on the provider. Later machines reuse the local copy.

What is in the box

  • The distribution’s official cloud image. The build checks it against the publisher’s checksum file.
  • The vagrant user with passwordless sudo. Vagrant replaces the well-known insecure SSH key with a new key pair on the first vagrant up.
  • A 40 GB virtual disk. The root filesystem grows to fill it on first boot.
  • SSH host keys generated on first boot, so machines created from the same box do not share them.
  • In the VirtualBox box, the VirtualBox Guest Additions.

Nothing else is installed. Add what your project needs with a provisioner.

Set CPU and memory

The VirtualBox box starts with 1 CPU and 1024 MB. With libvirt, the plugin’s own defaults apply. Set both explicitly:

Vagrant.configure("2") do |config|
  config.vm.box     = "cloudsoe/ubuntu-24.04"
  config.vm.box_url = "https://boxes.cloudsoe.com/cloudsoe/ubuntu-24.04.json"

  config.vm.provider :virtualbox do |vb|
    vb.cpus   = 2
    vb.memory = 4096
  end

  config.vm.provider :libvirt do |lv|
    lv.cpus   = 2
    lv.memory = 4096
  end
end

Synced folders

  • VirtualBox: the project directory is mounted at /vagrant as a VirtualBox shared folder. The Guest Additions are already in the box.
  • libvirt: vagrant-libvirt syncs /vagrant with NFS or rsync, depending on what your host provides. To force rsync:
config.vm.synced_folder ".", "/vagrant", type: "rsync"

Limitations

  • amd64 only. There is no arm64 box, so the boxes do not run on Apple silicon Macs.
  • VirtualBox and KVM cannot run virtual machines at the same time on one Linux host. Stop the machines of one before starting the other.

Next steps