vagrant/website/source/docs/vagrant-cloud/boxes/create.html.md

layout	page_title	sidebar_current
docs	Creating a New Vagrant Box	vagrant-cloud-boxes-create-x

Creating a New Vagrant Box

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

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

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

All three options require you sign up for Atlas.

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 Atlas, keeping a history along the way.

Creating Boxes via the Atlas 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 Atlas.

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 Boxes API to upload boxes with curl. To get started, you'll need to get an access token.

Then, prepare the upload:

$ curl 'https://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_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://atlas.hashicorp.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME?access_token=ACCESS_TOKEN'

Your box should then be available for download.