How to Setup and Use a Vagrant Box

Introduction: How to Setup and Use a Vagrant Box

This might be useful if you need a Linux environment for development and you don't want install a Linux distribution with dual-boot.

The advantage over running a regular VM with VirtualBox (I will use VirtualBox as an example in this tutorial because it is free and easy to use) is that the Vagrant box will run without the GUI. This makes it run better especially on older machines (like mine). Another advantage could be that you can use PuTTY (or your favorite ssh client) to run commands. Some people prefer doing it this way instead of using the VirtualBox window that shows you the video output of the VM.

To have the advantages mentioned above, you could run an instance of Ubuntu server (or another distro or flavor that does not come with a GUI) in headless mode.
This is also what Vagrant does, but it will also give you the following advantages:

  • you don't have to actually install the operating system. Vagrant will take care of the whole setup
  • you can use cmd or powershell (assuming that you are on windows) to create, start, stop, delete, revert (and more) your VMs

Teacher Notes

Teachers! Did you use this instructable in your classroom?
Add a Teacher Note to share how you incorporated it into your lesson.

Step 1: Download and Install the Tools

First, we need to download and install the tools that we will use:

  • Download VirtualBox from here and install it

  • Download Vagrant from here and install it

  • Download PuTTY from here

  • Download PuTTYgen from here

(You don't need to install PuTTY and PuTTYgen. Just download the binaries)

Step 2: Find the OS That You Want to Run

Look for the Operating System that you want to run in the catalog found on the official website: link

Step 3: Prepare the CMD Window Where You Will Run the Necessary Commands

Go and create a new folder on your hard drive. That folder will be the shared folder between the virtual machine and your host machine.

Now hold the 'Shift' key and right-click on that folder and select "Open command windows here" and you will open a CMD windows in that location.

Step 4: Prepare Your Vagrantfile

Prepare your vagrantfile (a file that contains some settings for your virtual machine) by running "vagrant init " where you replace with an operating system that is found in the catalog

Common examples:

  • For running Ubuntu 16.04 run "vagrant init ubuntu/xenial64"
  • For running Ubuntu 14.04 run "vagrant init ubuntu/trusty64"
  • For running Fedora 23 run "vagrant init fedora/23-cloud-base"
  • For running Centos 7 run "vagrant init centos/7"

Step 5: Start Up Your Virtual Machine

Start your virtual machine by running "vagrant up" (Do this on the same command prompt)

An OS image will be downloaded and installed. It should look similar to the screenshot.

Step 6: Prepare the Private Key That You Will Use to Login Into the Machine

After the virtual machine is started you can't interact with it since you don't have the VirtualBox GUI so you will have to treat it as a remote machine and login by using SSH (not the most accurate way to say it, but I think this will do). Some Vagrant images will set a default uesrname/password combination, others will generate a random key and place it in a newly created file. The best way to interact with this boxes is to use a RSA key pair. Usually, Vagrant will generate a private key and a public key when creating a new VM (as a result of the 'vagrant up' command). To import the generated private key into the SSH client that you will use (PuTTY) you will have to use PuTTYgen.

Start PuTTYgen and click the "Load" button and go to the folder where you just ran "vagrant up" and go to .vagrant\machines\default\virtualbox
Near the "File Name" menu you have a dropdown menu for selecting extensions. Select "All files" from there and then select the file named "private_key" and click "Open" Click the "Save private key" button and answer yes if you're asked if you're sure that you want to save it without a passphrase. Save it with a name that will be easy to recognize. I picked "private_key_putty"

Step 7: Login Into the Virtual Machine

Open PuTTY and write "" as the Host Name, 2222 as the port and then go to Connection->SSH->Auth and click the "Browse" button under the "Private key file for authentication" field. Here, select the private_key_putty file that you generated at the previous step.

(The details for your box might be different. To see details about that run "vagrant ssh")

Extra: Now go back to Session and you will be able to save the settings for this session so you won't have to input them again (Input a name in the "Saved Sessions" field and click "Save").

Click "Open" and you will be prompted to enter the user you want to login as. You can get the default user from the OS catalog mentioned in a previous step (or by running "Vagrant ssh").

For example the default user for Ubuntu distributions is ubuntu and the default one for Fedora is vagrant

Extra tips:

  • In PuTTY, go to Connection->Data and input the user that you can use to log in in the 'Auto-login username' field. This way, you won't have to input any data when setting up a ssh connection.
  • To improve the security of your box you could change the password for the existing user to make sure that you're not running a ssh service with a default username/password combination
  • Possible challenge: Create a new user and make it so that you can use your private key (not the generated one) for logging in

Step 8: Using the Virtual Machine

Now you will be able to use the vagrant box for development. You can manage the newly created VM using vagrant.

Some simple and useful vagrant commands are:

  • "vagrant up" - starts the box. After that's done you can connect to it using PuTTY
  • "vagrant halt" - stops the box.
  • "vagrant init" - generates the vagrantfile corresponding to the distribution that you picked
  • "vagrant destroy" - deletes the box

For more information you can always visit the official website:

I recommend that you also look into snapshots and reverts since these might be useful if you are doing development work.

Be the First to Share


    • Trash to Treasure Contest

      Trash to Treasure Contest
    • Raspberry Pi Contest 2020

      Raspberry Pi Contest 2020
    • Wearables Contest

      Wearables Contest



    3 years ago

    Thanks for sharing :)