Tails can be built in a virtual machine that is managed using Vagrant and vagrant-libvirt. Here lies more details on how Tails uses Vagrant, its configuration, and how to create and upload the template virtual machine.


Vagrant support files are located in the vagrant directory at the root of the amnesia.git repository.

This directory contains:

  • Vagrantfile: configuration file for Vagrant,
  • provision/setup-tails-builder: idempotent provisioning script that is run inside the virtual machine upon boot,
  • provision/assets/build-tails: build script to be run inside the virtual machine,
  • for building the base box:
    • definitions/tails-builder/generate-tails-builder-box.sh: Script that generates the base box. The box naming format and disk size is specified in this script, as well as the vmdebootstrap parameters (Debian distribution, architecture, etc).
    • definitions/tails-builder/postinstall.sh: Script that is run inside the base box before finalizing it, e.g. for installing the packages we need.

We choose to use the Shell provisioner, as long as we make this script reentrant it will lower the learning curve for contributors not familiar with Puppet or Chef.

The Vagrantfile will share the .git directory of the local clone of the repository. This is done to overcome limitations of VirtualBox shared folders (namely symlink support). The build script will clone (and fetch further changes) that "bare" repository.

Creating the base box

The creation of the base box is fully automated using vmdebootstrap and vagrant-libvirt's create.box.sh script.

Installing the requirements

Debian packages:

sudo apt install vmdebootstrap vagrant-libvirt

Generating a new base box

Until Debian bug #823317 is solved, the vagrant-libvirt package in Debian is missing a script we depend on, so you have to copy create_box.sh to /usr/share/vagrant-plugins/vagrant-libvirt/tools/create_box.sh before attempting the following!

If needed, modify vagrant/definitions/tails-builder (e.g. if new packages are required, add them through postinstall.sh), and commit the changes. Then simply run:

rake basebox:create

Note that it will require you to be a sudoer and will ask you for your password.

Make Tails build with the new base box

Let's assume it's the most recent .box file in the current directory (which will be the case after generating a new base box), otherwise set BOX appropriately below:

BOX="$(ls -1tr vagrant/definitions/tails-builder/*.box | tail -n1)"
BOX_NAME="$(basename "${BOX}" .box)"
BOX_CHECKSUM="$(sha256sum "${BOX}" | cut -f 1 -d ' ' | tr -d '\n')"
sed -i \
    -e "s/^\(\s*config.vm.box\s*=\s*\).*$/\1'${BOX_NAME}'/" \
    -e "s/^\(\s*config.vm.box_download_checksum\s*=\s*\).*$/\1'${BOX_CHECKSUM}'/" \
git commit -m "Upgrade Vagrant base box to '${BOX_NAME}'." vagrant/Vagrantfile

If you want to use this base box locally, just add it with

vagrant box add "${BOX}"

If this base box is to be available from our mirrors, please upload it to the project/vagrant directory of our rsync server.