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.
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.
You'll first need to create a box file. This can be done via
or with Packer locally.
After you've created the
.box file, this guide can be followed.
Go to the Create Box page.
Name the box and give it a simple description
Create your first version for the box. This version must match the format
Create a provider for the box, matching the provider you need locally in Vagrant.
virtualboxis the most common provider.
.boxfile for each provider, or use a url to the
.boxfile 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.
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:
Then, upload your box with the following command, with the filename in this case being
$ 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.