Build a Desktop VM

In the following, we explain how to build your own custom Quantum Mobile VirtualBox image from scratch.

Calculate at around two hours for building the full VM:

Prerequisites & Installation

  • Operating system: Building Quantum Mobile has been tested on MacOS, Ubuntu and Windows.

  • Vagrant >= 2.0.1

  • VirtualBox >= 6.1.6

  • Python >= 3.6

Clone the repository:

git clone
cd quantum-mobile

Install tox and the vagrant-vbguest plugin:

pip install tox
# improves interface
vagrant plugin install vagrant-vbguest


For those using Conda, it is recommended to also install tox-conda:

pip install tox-conda

Create the Virtual Machine

See also

If you would like to customise any aspects of the VM, now would be a good time to do so.

Use tox to set up the Python environment and run the build steps.

tox -a -v        # shows available automations
tox -e vagrant

This will call vagrant up, to initialise the VM, which then calls ansible-playbook playbook-build.yml, to configure the VM and build the required software on it.


If you get an error during the installation of the VirtualBox Guest Additions, you may need to perform additional steps (see issue #60).


Building the Desktop Edition is tested on GitHub Actions on every commit to the repository. For the tested steps see the .github/workflows/build.yml file.

Continuing a failed build

If the build fails or is interrupted at any step (for example a failed download, due to a bad connection), you can continue the build with:

# output the vagrant box connection details
vagrant ssh-config > vagrant-ssh
tox -e ansible

The ansible automation steps are generally idempotent, meaning that if they have been previously run successfully, then they will be skipped in any subsequent runs.

Running only selected steps

All steps of the ansible build process are “tagged”, which allows you to select to run only certain steps, or skip others.

To list all the tags:

tox -e ansible -- --list-tags

or look at playbook-build.yml.

To run only certain tags, use either:

ANSIBLE_ARGS="--tags tag1,tag2 --skip-tags tag3" tox -e vagrant


tox -e ansible -- --tags tag1,tag2 --skip-tags tag3

Creating the image

First, clean unnecessary build files:

tox -e ansible -- --tags cleanup

Then run playbook-package.yml via:

tox -e package -- --skip-tags validate

This will compact the hard disk of the virtual machine and export the image and release notes to the dist/ folder.


The validate tag checks that the repositories git tag is the same as the vm_version specified in inventory.yml, and is only needed for new releases by Quantum Mobile maintainers.

Other Useful commands

  • vagrant reload: restart machine

  • vagrant halt: stop machine

Vagrant keeps information on how to connect in a folder called .vagrant. If you would like to create a new machine, vagrant destroy will remove the .vagrant folder and allow you to create a new VM (note: you may want to keep a copy in case you want to reconnect later).