--- a
+++ b/guide/using_vagrant.md
@@ -0,0 +1,150 @@
+# Using Vagrant
+
+[Vagrant](https://www.vagrantup.com/) is a command line utility for creating project-specific virtual machines (VMs).
+MedaCy uses Vagrant to enable development on different platforms, including Windows.
+This guide will instruct you on how to use Vagrant within PyCharm or from the command line.
+
+## Installations
+
+The only additional software you need to use Vagrant is VirtualBox and Vagrant itself.
+This guide assumes that if you plan to use PyCharm, you have the professional edition
+and are already familiar with how to use its base features.
+The full user guide for PyCharm can be found [here](https://www.jetbrains.com/help/pycharm/meet-pycharm.html).
+ 
+### Installing VirtualBox
+
+[VirtualBox](https://www.virtualbox.org/) is an open-source program for creating virtual machines.
+Vagrant will utilize it to create your medaCy virtual machine.
+You can download the version appropriate for your machine [here](https://www.virtualbox.org/wiki/Downloads)
+and follow the installation instructions that they provide.
+
+### Installing Vagrant
+
+Go to the [installation page](https://www.vagrantup.com/downloads.html) for Vagrant and select the version
+appropriate for your machine. You will likely need to restart your machine after this step.
+
+Please also run this command to allow for the customization of the Vagrant box's disk size:
+```bash
+$ vagrant plugin install vagrant-disksize
+```
+
+## Vagrant for medaCy
+
+Each project that uses Vagrant requires there to be a file in the root directory of the project named
+Vagrantfile. MedaCy distributes with this file already configured. 
+
+### At the command line
+
+### Vagrant up
+
+This step includes downloading an Ubuntu operating system and should be performed with a strong internet
+connection for fastest results.
+
+From the command line, navigate to the directory containing your clone of medaCy, and run this command:
+
+```bash
+$ vagrant up
+```
+
+This command will create your new medaCy VM using the specifications in the Vagrantfile.
+You will be using this command every time you want to start up your VM, 
+but since this is its first activation, it will take a while.
+While you wait, the operating system for the medaCy VM (Ubuntu), Python 3, and medaCy and all its dependencies
+are being downloaded and installed. Once these downloads complete, 
+you won't have to wait for them every time you run `vagrant up`.
+
+### Let's take a look
+
+Now run:
+
+```bash
+$ vagrant ssh
+```
+
+When this command finishes, you'll be inside your new VM. Specifically, you'll be in the home folder.
+You don't particularly need to be here, so run these commands:
+
+```bash
+vagrant@ubuntu-bionic:~$ cd ../..
+vagrant@ubuntu-bionic:/$ cd vagrant
+vagrant@ubuntu-bionic:/vagrant$ ls
+```
+
+After running the first command, you could run `ls` to see the root directory of your 
+VM, if you feel so inclined. We're interested in what's in the `/vagrant` subdirectory. 
+The `/vagrant` directory of the VM contains your copy of the medaCy repository, and is shared between the 
+VM and the directory on the host machine containing the Vagrantfile.
+
+### So should I continue by setting up a virtual environment for medaCy?
+
+No. Think of your VM as an enhanced virtual environment. When the VM was created, medaCy
+ and all of its dependencies were installed on the base installation of Python 3.
+ In theory, you'll only be using this VM for medaCy, so there's no need to 
+ create a separate environment for it.
+ 
+Because of how Python 3 was installed on the VM, you will need to use the command `Python3` rather than `Python`,
+and `pip3` instead of `pip`; `pip3` may require using `sudo`.
+ 
+### What now?
+
+Now that you have a medaCy-specific Ubuntu VM with a shared folder between the VM and your machine,
+you can edit any file you'd like in whatever text editor you choose, then run it within the VM from
+the command line. You won't need to worry about whether or not medaCy is compatible with your host machine.
+
+Keep in mind that the VM has limited resources and should only be used for developing
+medaCy itself and generating predictions. Model training requires significantly more resources and 
+should be done on a machine with a significant amount of memory.
+
+### Exiting and turning off the VM
+
+Having a VM running requires a lot of resources from your host machine. When you're
+done using the VM, run these commands.
+
+```bash
+vagrant@ubuntu-bionic:~$ exit
+$ vagrant halt
+```
+
+`$ exit` will leave the VM from the command line but leave it running in the background;
+`$ vagrant halt` will turn it off.
+
+## In PyCharm
+
+### Tools > Vagrant > Up
+
+PyCharm Professional Edition provides features for interacting with Vagrant VMs.
+This guide will cover the basics, but the developers of PyCharm provide a guide [here](https://www.jetbrains.com/help/pycharm/vagrant-support.html).
+
+Open your medaCy project in PyCharm and select Tools > Vagrant > Up. This is the same
+as running `vagrant up` from the terminal.
+
+### Tools > Start SSH session...
+
+Likewise, Tools > Start SSH session... is the same as `$ vagrant ssh`. PyCharm will list
+your Vagrant VM as an option to SSH into. You will then be able to interact with the VM at
+its own terminal.
+
+From Tools > Vagrant, you also have the option to select Halt.
+
+### Configuring the interpreter
+
+While you're developing medaCy in PyCharm, you probably don't want to run each script from the command line.
+This section details how to set the project interpreter to be the installation of Python 3 on the VM.
+
+Select File > Settings, and then on the settings menu, select Plugins. Enable the
+Remote Interpreter plugin. 
+
+Once remote interpreters are enabled for PyCharm, you will need to configure the remote interpreter
+for this project. The plugin is already designed to work with Vagrant, so this will be easy.
+
+Again, go to File > Settings, and select Project: medacy > Project Interpreter. Select the gear
+icon on the right side of the dialogue box and select "add". Another dialogue box will appear.
+Select "Vagrant" on the left side of the new box. Set the Python interpreter path to 
+`usr/bin/python3`.
+
+## Finishing up
+
+We hope that this guide was able to clarify how to configure Vagrant for medaCy.
+Should you encounter any issues, please follow the links throughout the guide
+to read the documentation for Vagrant and PyCharm. If you believe the problem is 
+specific to Vagrant is configured for this project, please [open a new issue](https://github.com/NLPatVCU/medaCy/issues).
\ No newline at end of file