Box Repository

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.

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.