Creating a New Vagrant Box

This page will cover creating a new box in Vagrant Cloud and how to distribute it to users. Boxes can be distributed without Vagrant Cloud, but miss out on several important features.

There are three ways to create and upload Vagrant Boxes to Vagrant Cloud. All three options are outlined below.

We recommend using Packer, as it is fully repeatable and keeps a strong history of changes within Vagrant Cloud. However, for some situations, including legacy workflows, the Web UI or API will work well.

All three options require you sign up for Vagrant Cloud.

Creating Boxes with Packer

Using Packer requires more up front effort, but the repeatable and automated builds will end any manual management of boxes. Additionally, all boxes will be stored and served from Vagrant Cloud, keeping a history along the way.

Creating Boxes via the Vagrant Cloud Web Interface

You'll first need to create a box file. This can be done via the vagrant package command or with Packer locally.

After you've created the .box file, this guide can be followed.

1. Go to the Create Box page.

2. Name the box and give it a simple description

3. Create your first version for the box. This version must match the format [0-9].[0-9].[0-9]

4. Create a provider for the box, matching the provider you need locally in Vagrant. virtualbox is the most common provider.

5. Upload the .box file for each provider, or use a url to the .box file that is publicly accessible

You can find all of your boxes in the Vagrant section of Vagrant Cloud.

Once you've created and released a box, you can release new versions of the box by clicking "Create New Version" under the versions sidebar on a box page. For more information on the release lifecycle of boxes, see the help page dedicated to box lifecycle.

Creating Boxes with the API

This example uses the API to upload boxes with curl. To get started, you'll need to get an access token.

Then, prepare the upload:

$ curl 'https://vagrantcloud.com/api/v2/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_NAME/ARCHITECTURE_NAME/upload?access_token=ACCESS_TOKEN'

This should return something like this:

{
  "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e"
}

Then, upload your box with the following command, with the filename in this case being foo.box:

$ curl -X PUT --upload-file foo.box https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e

When the upload finishes, you can verify it worked by making this request and matching the hosted_token it returns to the previously retrieved upload token.

$ curl 'https://vagrantcloud.com/api/v2/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME/ARCHITECTURE_NAME?access_token=ACCESS_TOKEN'

Your box should then be available for download.