Version 1

This documentation is for Deis v1 PaaS. For Workflow (v2) documentation visit


Vagrant is a tool for building complete development environments with a focus on automation. This guide demonstrates how you can stand up a Deis cluster for development purposes using Vagrant.

Please get the source and refer to the Vagrantfile while following this documentation.

Install Prerequisites

Please install Vagrant v1.6.5+ and VirtualBox.

The Vagrantfile requires the plugin vagrant-triggers. To install the plugin run:

$ vagrant plugin install vagrant-triggers


For Ubuntu users: the VirtualBox package in Ubuntu has some issues when running in RAM-constrained environments. Please install the latest version of VirtualBox from Oracle’s website.

Generate a New Discovery URL

A discovery URL links etcd instances together by storing their peer addresses and metadata under a unique identifier. Run this command from the root of the repository to generate a contrib/coreos/user-data file with a new discovery URL:

$ make discovery-url

Required scripts are supplied in this user-data file, so do not provision a Deis cluster without running make discovery-url.

Generate SSH Key


For Vagrant clusters you don’t need to create a key pair, instead use the insecure_private_key located in ~/.vagrant.d/insecure_private_key.

Boot CoreOS

Start the CoreOS cluster on VirtualBox. From a command prompt, switch directories to the root of the Deis project and type:

$ vagrant up

This instructs Vagrant to spin up 3 VMs. To be able to connect to the VMs, you must add your Vagrant-generated SSH key to the ssh-agent (deisctl requires the agent to have this key):

$ ssh-add ~/.vagrant.d/insecure_private_key

Configure DNS

For convenience, we have set up a few DNS records for users running on Vagrant. is set up for 3-node clusters and is set up for 5-node clusters.

Since is your cluster domain, use anywhere you see in the documentation.

It is not necessary to configure DNS for Vagrant clusters, but it is possible - if you want to set up your own DNS records, see Configure DNS for more information.

Install Deis Platform

Now that you’ve finished provisioning a cluster, please refer to Install the Deis Platform to start installing the platform.