Box Providers API

Providers contain the pointers to the box files, be it a hosted or self-hosted box. Box versions can have many providers, each which represents a Vagrant compatible provider, either from Vagrant Core as a 3rd party plugin.

Hosted Boxes

The provider API is used to host boxes. To create a hosted box, simply omit the URL parameter. You will then be able to use the upload endpoint to upload a box to us.

The upload endpoint responds with a 302 FOUND HTTP response, redirecting you to the final location for upload. Your HTTP client will need to be configured to follow redirects for this to work.

Box Provider Attributes

Attribute Description Required
name The name of the provider. Vagrant will use this to determine compatible boxes on the client. Common providers include virtualbox, vmware_desktop, aws, digitalocean, docker, google, hyperv, rackspace, parallels, and veertu Yes
url An HTTP URL to the box file. This must be accessible at this URL from the machine where you expect a user to download the box by using Vagrant. If ommitted, we assume you wish to host the provider on Atlas. No


The following actions can be perfomed on this resource.

GET /api/v1/box/:username/:name/version/:number/provider/:name
POST /api/v1/box/:username/:name/version/:number/providers
PUT /api/v1/box/:username/:name/version/:number/provider/:name
DELETE /api/v1/box/:username/:name/version/:number/provider/:name
GET /api/v1/box/:username/:name/version/:number/provider/:name/upload
GET /:username/:name/version/:number/provider/


Create a provider

$ curl \
    -X POST \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d provider[name]='virtualbox'

Retrieve a provider

$ curl \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Update a provider

$ curl \
    -X PUT \
    -H "X-Atlas-Token: $ATLAS_TOKEN" \
    -d provider[name]='vmware_desktop'

Destroy a provider

$ curl \
    -X DELETE \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

Upload a .box file for a provider

Uploading a box for a provider is a two-step process. First, you must make a GET request to the /upload endpoint for the provider:

$ curl \
    -H "X-Atlas-Token: $ATLAS_TOKEN"

This response body will be JSON of the form:

  "upload_path": ""

The value in the upload_path key is a uniquely generated, time-sensitive URL. The second step in the upload process is to PUT (upload) your raw box fie to the upload_path:

$ curl -X PUT --upload-file /path/to/
Download a .box for a provider
$ curl \
    -L \
    -X GET \
    -H "X-Atlas-Token: $ATLAS_TOKEN"