--- a
+++ b/docs/getting_started/vagrant.md
@@ -0,0 +1,95 @@
+# Running HippUnfold with a Vagrant VM
+
+This option uses Vagrant to create a virtual machine that has Linux
+and Singularity installed. This allows you to use Singularity to run HippUnfold 
+from a clean environment, whether you are running Linux, Mac or Windows (since all
+three are supported by Vagrant). Note: VirtualBox does the actual 
+virtualization in this example, but Vagrant provides an easy and reproducible way to create and 
+connect to the VMs (as shown below).
+
+
+## Install VirtualBox and Vagrant
+
+The example below uses Vagrant and VirtualBox installed on Ubuntu 20.04. 
+
+The [Vagrant install instructions](https://developer.hashicorp.com/vagrant/downloads) describe
+what you need to do to install on Mac, Windows or Linux.
+
+Vagrant must use a **provider** for the actual virtualization. The instructions here assume you
+are using VirtualBox for this, since it is free and easy to use, but in principle should work with any
+virtualization provider.  The [VirtualBox downloads page](https://www.virtualbox.org/wiki/Downloads) 
+can guide you through the process of installing it on your system (Mac, Windows, Linux supported).
+
+
+## Create a Vagrant Box 
+
+Once you have Vagrant and VirtualBox installed, the following screencast demonstrates 
+how you can setup a Box with Singularity pre-loaded on it. The main steps are to 1) create a Vagrantfile, 2) start the box using `vagrant up`, and 3) connect to it using `vagrant ssh`.
+
+Note: These screencasts are more than just videos, they are asciinema recordings -- you can pause them and then copy-paste text
+directly from the asciinema cast!
+
+```{asciinema} ../casts/vagrant_hippunfold_setup.cast
+---
+preload: 1
+speed: 2
+---
+```
+
+This is the `Vagrantfile` used in the video, for quick reference:
+```
+Vagrant.configure("2") do |config|
+  config.vm.box = "sylabs/singularity-3.7-ubuntu-bionic64"
+  config.vm.provider "virtualbox" do |vb|
+     vb.cpus = 8
+     vb.memory = "8096"
+   end
+end
+```
+
+
+## Download the test dataset
+
+We are downloading the test dataset with the following 
+command:
+```
+wget https://www.dropbox.com/s/mdbmpmmq6fi8sk0/hippunfold_test_data.tar
+```
+
+
+```{asciinema} ../casts/vagrant_hippunfold_get_data.cast
+---
+preload: 1
+speed: 2
+---
+```
+
+
+## Download the HippUnfold container
+
+We pull/build the container from DockerHub:
+```
+singularity pull docker://khanlab/hippunfold:latest
+```
+
+## Run HippUnfold
+This demonstrates the basic HippUnfold options, and how
+to perform a dry-run:
+
+```{asciinema} ../casts/vagrant_hippunfold_dryrun.cast
+---
+preload: 1
+speed: 2
+---
+```
+
+Finally, we can run HippUnfold using all the cores:
+
+```{asciinema} ../casts/vagrant_hippunfold_run.cast
+---
+preload: 1
+speed: 2
+---
+```
+
+