Factodus

HCP Vagrant shuts down: where to move your Vagrant boxes, and what each option keeps

By Factodus · updated

HashiCorp is retiring HCP Vagrant, the registry that used to be Vagrant Cloud and that answers every vagrant box add org/name. The end-of-life notice gives three dates:

Date What happens
1 October 2026 No new boxes can be created
2 November 2026 End of support and maintenance
31 December 2026 End of operations: boxes are no longer served

Looking for a specific public box? The Vagrant boxes directory lists the most downloaded ones with their versions and providers.

The Vagrant CLI itself stays open source and keeps working. What goes away is the place your boxes are downloaded from, so every Vagrantfile with config.vm.box = "acme/base" and every CI job that runs vagrant box add or vagrant up on a fresh runner will fail on 1 January.

Short version. Export your boxes now, whatever you pick later: the export guide does it with curl and jq. Then choose between a static metadata.json (free or nearly, public boxes, a URL in every Vagrantfile) and a registry that speaks the Vagrant Cloud API (box names, versions and private boxes keep working through VAGRANT_SERVER_URL).

What Vagrant needs from a box host

When you write config.vm.box = "acme/base", Vagrant asks the server named by VAGRANT_SERVER_URL (HCP by default) for a JSON document listing every version of acme/base, its providers, architectures, download links and checksums. That one document is what gives you:

  • short names like acme/base instead of a URL;
  • versions: config.vm.box_version = "~> 2.0", vagrant box outdated, vagrant box update;
  • providers and architectures: the same name serving VirtualBox, libvirt, VMware, amd64 and arm64;
  • private boxes: the server checks the token Vagrant sends from VAGRANT_CLOUD_TOKEN.

Every option below is a different answer to the question “who serves that JSON document?”.

Option 1: a static metadata.json on S3, R2, GitLab or a web server

Vagrant accepts the same JSON document from any URL. Put the box files and a hand-written (or generated) metadata.json on any static host and point Vagrantfiles at it:

config.vm.box     = "acme/base"
config.vm.box_url = "https://boxes.example.com/acme/base/metadata.json"
  • Keeps: versions and version constraints, checksums, several providers and architectures.
  • Loses: the short name on its own: each Vagrantfile needs the box_url line, and so does every vagrant box add in CI. Private boxes are hard: Vagrant sends no credentials to a plain file host, so in practice the files must be public or behind your VPN.
  • Costs: storage plus download traffic. On AWS S3 traffic is about $0.09 per GB after the first 100 GB a month, which adds up with multi-GB boxes and busy CI; Cloudflare R2 charges nothing for downloads.

Several open-source box publishers are planning this, for example the bento proposal to use GitLab packages and Pages. The export guide produces exactly this layout.

Option 2: a binary repository you may already run

JFrog Artifactory has a Vagrant repository type, so if your company already pays for it, boxes can live next to your other artifacts. Check that your plan includes it and that your CI runners can reach it.

Option 3: a registry that speaks the Vagrant Cloud API

Vagrant 2.4 talks to any server that answers the same API as HCP. Set one environment variable on developer machines and CI runners and nothing else changes:

export VAGRANT_SERVER_URL=https://boxes.example.com
export VAGRANT_CLOUD_TOKEN=<token>   # only for private boxes
vagrant box add acme/base            # same name as before
  • Keeps: short names, versions, providers, architectures, private boxes with a token, no edits to Vagrantfiles.
  • Needs: someone to run the server, or a hosted one.

BoxHarbor is such a registry, with a migrator that copies every version, provider and architecture from HCP and checks the checksums. You can try the API right now against a demo box:

VAGRANT_SERVER_URL=https://boxes.factodus.com vagrant box add demo/tiny

Packer pipelines

If Packer publishes your boxes with the vagrant-registry post-processor, that step stops working with HCP. Keep the vagrant post-processor that builds the .box file, and replace the upload: copy the file to your static host and regenerate metadata.json (option 1), or upload it to your registry from a shell-local post-processor (option 3).

A checklist for December

  1. Export every box and version you still use, including old versions pinned in long-lived projects.
  2. Pick the host, upload, and test vagrant box add from a clean machine.
  3. Update Vagrantfiles (box_url) or CI environment (VAGRANT_SERVER_URL) before 31 December.
  4. Fix Packer post-processors so new versions land in the new place.