Box File Format

A Vagrant .box file is a tarball (tar, tar.gz, zip) that contains all the information for a provider to launch a Vagrant machine.

There are four different components that make up a box:

• VM artifacts (required) - This is the VM image and other artifacts in the format accepted by the provider the box is intended for. For example, a box targeting the VirtualBox provider might have a .ofv file and some .vmdk files.

• metadata.json (required) - Contains a map with information about the box. Most importantly the target provider.

• info.json - This is a JSON document that can provide additional information about the box that displays when a user runs vagrant box list -i. More information is provided here.

• Vagrantfile - The Vagrantfile embedded in the Vagrant box will provide some defaults for users of the box. For more information on how Vagrant merges Vagrantfiles including ones sourced within the box file see the Vagrantfile docs

So, if you extract a box and look at it's contents it will look like:

# contents of the hashicorp/bionic64 box
# ref: https://app.vagrantup.com/hashicorp/boxes/bionic64
$ ls hashicorp_bionic_box  
Vagrantfile                     metadata.json
box.ovf                         ubuntu-18.04-amd64-disk001.vmdk

Box metadata.json

Within the archive, Vagrant does expect a single file: metadata.json. There is only one metadata.json per box file. metadata.json must contain at least the "provider" key with the provider the box is for. Vagrant uses this to verify the provider of the box. For example, if your box was for VirtualBox, the metadata.json would look like this:

{
  "provider": "virtualbox"
}

If there is no metadata.json file or the file does not contain valid JSON with at least a "provider" key, then Vagrant will error when adding the box, because it cannot verify the provider.

Other keys/values may be added to the metadata without issue. The value of the metadata file is passed opaquely into Vagrant and plugins can make use of it. At this point, Vagrant core does not use any other keys in this file.