Simple CLI tool for managing Vagrant repositories
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

vgrepo Build Status Go Report Card

HashiCorp company does Vagrant for managing the lifecycle of virtual machines. It is great, but they do not provide any open source tools for versioning and discovering your own images without a necessity to have an account on HashiCorp Atlas.

vgrepo is a simple CLI tool for managing Vagrant repositories. In pair with HTTP server it provides simple way to distribute your images without worries about manual upgrading them on your team.




Before the initial install allows git to use redirects for service (reason why you should do this described here):

git config --global http. true

To build the vgrepo from scratch, make sure you have a working Go 1.5+ workspace (instructions), then:

go get

If you want update vgrepo to latest stable release, do:

go get -u

Getting started

  1. Specify storage settings in the /etc/vgrepo/vgrepo.conf configuration file. Parameter path is a directory that contains repositories with their metadata: name, versions and providers of VMs. Parameter url is used to discover your images and provides a permanent link to metadata.
  # Repository URL and port
  url: http://vagrant.example.tld
  # Repository path to store images and metadata
  path: /srv/storage
  1. Create directory for the repository path /srv/storage and make sure that it is writable.

  2. Add the image to the repository:

vgrepo add /path/to/ powerbox 1.0.0 virtualbox
  1. Configure NGINX to serve static files from /srv/storage directory.
server {
    listen 80;
    server_name vagrant.example.tld;
    access_log off;
    error_log off;
    root /srv/storage;
    location / {
        autoindex on;
        expires -1;

Done. After adding changes you can specify URL http://vagrant.example.tld/metadata/powerbox/powerbox.json in the config.vm.box_url to force Vagrant checking updates every time you run command vagrant up.


Imagine you have an image with the name powerbox. The standard path for metadata will be http://vagrant.example.tld/metadata/powerbox/powerbox.json, however it looks awful and unmemorable. You can use well-looking URL instead of direct link to JSON metadata file with the following NGINX configuration of the virtual host:

server {
    listen 8080;
    server_name vagrant.example.tld;

    root /srv/storage;

    location ~ ^/r/([^\/]+)$ {
        return 301 $uri/;

    location ~ ^/r/([^\/]+)/$ {
        index /metadata/$1/$1.json;
        try_files /metadata/$1/$1.json =404;

    location ~ \.json$ {
        add_header Content-Type application/json;

    location ~ \.box$ {
        add_header Content-Type application/octet-stream;

    location / {
	    autoindex off;
        expires -1;

Now you are able to distribute your images for more than one machine over HTTP or HTTPS with a short and nice URLs with a format http://vagrant.example.tld/r/powerbox.


Usage: vgrepo {options} {command}


  add source name version provider    Add image to the Vagrant repository
  list                                Show the list of available images
  delete name version provider        Delete the image from the repository
  info name                           Display info of the particular repository
  render output template              Create index by given template file
  help                                Display the current help message


  --no-color, -nc    Disable colors in output
  --help, -h         Show this help message
  --version, -v      Show version


  vgrepo add $HOME/ powerbox 1.1.0 virtualbox
  Add image to the Vagrant repository

  vgrepo list
  Show the list of available repositories

  vgrepo delete powerbox 1.1.0
  Remove the image from the repository

  vgrepo info powerbox
  Show detailed info about the repository

  vgrepo render index.html /etc/vgrepo/templates/default.tpl
  Create index file by given template with output index.html


Released under the MIT license (see LICENSE)

Sponsored by FunBox