Box Repository

Note

HashiCorp has deprecated Vagrant Cloud and migrated the boxes to HCP Vagrant Registry. Read the documentation to learn more about HCP Vagrant Registry.

A Vagrant Box Repository provides Vagrant with some boxes and information on how to get the boxes. This can exist on a local filesystem or a service like Vagrantcloud.

There are two components that make up a Box Repository:

Vagrant Boxes - These are Vagrant .box files. See the box documentation for more information on Vagrant boxes.
Box Catalog Metadata - This is a JSON document (typically exchanged during interactions with HashiCorp's Vagrant Cloud) that specifies the name of the box, a description, available versions, available providers, and URLs to the actual box files (next component) for each provider and version. If this catalog metadata does not exist, a box file can still be added directly, but it will not support versioning and updating.

Box Catalog Metadata

The metadata is an optional component for a box (but highly recommended) that enables versioning, updating, multiple providers from a single file, and more.

You do not need to manually make the metadata. If you have an account with HashiCorp's Vagrant Cloud, you can create boxes there, and HashiCorp's Vagrant Cloud automatically creates the metadata for you. The format is still documented here.

It is a JSON document, structured in the following way:

{
  "name": "hashicorp/bionic64",
  "description": "This box contains Ubuntu 18.04 LTS 64-bit.",
  "versions": [
    {
      "version": "0.1.0",
      "providers": [
        {
          "name": "virtualbox",
          "url": "http://example.com/bionic64_010_virtualbox.box",
          "checksum_type": "sha1",
          "checksum": "foo",
          "architecture": "amd64",
          "default_architecture": true
        }
      ]
    }
  ]
}

As you can see, the JSON document can describe multiple versions of a box, multiple providers, and can add/remove providers/architectures in different versions.

This JSON file can be passed directly to vagrant box add from the local filesystem using a file path or via a URL, and Vagrant will install the proper version of the box. In this case, the value for the url key in the JSON can also be a file path. If multiple providers are available, Vagrant will ask what provider you want to use.