Building vagrant boxes

Thursday. August 14, 2025 - 6 mins

vagrant virtualization hashicorp

Vagrant is a powerful tool for creating reproducible dev environments, and sharing your custom Vagrant boxes on Vagrant Cloud makes it easy for other people to use them. Many times there are popular boxes, like ubuntu or red hat boxes, that are hard to find or disappear. In this post I want to walk through creating a Vagrant box from a VirtualBox vm.

Prerequisites

VirtualBox and Vagrant installed on your system.
An Ubuntu Server ISO (example: Ubuntu 20.04 LTS) for the base VM.
A Vagrant Cloud account (sign up if you don’t have one).
Command line and virtualization knowledge.

Create a Vagrant Box

Set Up the Base vm

Start by creating a vm in VirtualBox:

Create a New VM:
- Name: vagrant-ubuntu
- Type: Linux, Version: Ubuntu (64-bit)
- Memory: At least 512MB
- Disk: VMDK format, 40GB (dynamic allocation)
- Network: NAT with port forwarding (Host: 2222, Guest: 22 for SSH)
Install Ubuntu Server:
- Mount the Ubuntu ISO and install the OS.
- Set the username to vagrant and password to vagrant.
- Set the hostname to vagrant-ubuntu.

Configure the VM for Vagrant

Log into the VM and configure it to meet Vagrant’s requirements:

Set Root Password:
```
 sudo passwd root
```
Set the password to vagrant.
Enable Passwordless Sudo Access:
```
 sudo visudo -f /etc/sudoers.d/vagrant
```
Add the following line:
```
 vagrant ALL=(ALL) NOPASSWD:ALL
```
Save and test with sudo pwd (it should not prompt for a password).

Update the OS:

 sudo apt-get update -y
 sudo apt-get upgrade -y
 sudo apt-get install -y openssh-server
 sudo shutdown -r now

Install Vagrant SSH Key:

 mkdir -p /home/vagrant/.ssh
 chmod 0700 /home/vagrant/.ssh
 wget --no-check-certificate https://raw.githubusercontent.com/hashicorp/vagrant/master/keys/vagrant.pub -O /home/vagrant/.ssh/authorized_keys
 chmod 0600 /home/vagrant/.ssh/authorized_keys
 chown -R vagrant:vagrant /home/vagrant/.ssh

Clean Up the VM: Free up space and zero out the disk for better compression:

 sudo apt-get clean
 sudo dd if=/dev/zero of=/EMPTY bs=1M || true
 sudo rm -f /EMPTY
 sudo shutdown -h now

Package the VM into a Vagrant Box

On your host machine:

Create a vagrant directory to keep the boxes:

 mkdir ~/vagrant-boxes && cd ~/vagrant-boxes

Package the VM (the real magic):
```
 vagrant package --base vagrant-ubuntu --output ubuntu.box
```
- –base: The name of the VM in VirtualBox (‘vagrant-ubuntu’).
- –output: The name of the output box file (‘ubuntu.box’).

Test the Box Locally (kinda Optional but worth checking)

To ensure the box works:

Create a test directory:

 mkdir test-box && cd test-box
 vagrant init

Edit the Vagrantfile:

 Vagrant.configure("2") do |config|
   config.vm.box = "ubuntu"
   config.vm.box_url = "file:///path/to/vagrant-boxes/ubuntu.box"
 end

Test the box:
```
 vagrant up
 vagrant ssh
```

Clean up and delete after testing:

 vagrant destroy -f
 cd .. && rm -rf test-box

Create a Vagrant Cloud Account

Go to Vagrant Cloud and sign up or log in.
Create a new box:
- Navigate to Create Box.
- Enter a box name (e.g., yourusername/ubuntu2004).
- Set visibility (public or private) and add a description.

Install the Vagrant Cloud CLI

Install the Vagrant Cloud plugin:

vagrant plugin install vagrant-cloud

Authenticate with Vagrant Cloud

vagrant cloud auth login

Enter your username and password or an access token (generate one from your Vagrant Cloud account settings).

Create a Version for Your Box

Create a version for your box:

vagrant cloud version create yourusername/ubuntu2004 1.0.0

Replace yourusername/ubuntu with your box name.
Use a version number like ‘1.0.0’.

Create a Provider

Add a VirtualBox provider for the version:

vagrant cloud provider create yourusername/ubuntu2004 virtualbox 1.0.0

Upload the Box File

Upload the box file to Vagrant Cloud:

vagrant cloud provider upload yourusername/ubuntu2004 virtualbox 1.0.0 ~/vagrant-boxes/ubuntu.box

Publish the Box

Release the version to make it available:

vagrant cloud version release yourusername/ubuntu2004 1.0.0

Your box is now live on Vagrant Cloud. Test and share the box now.

Test the Box from Vagrant Cloud

Test the box by initializing it from Vagrant Cloud:

Create a new Vagrantfile in a new file:

   Vagrant.configure("2") do |config|
     config.vm.box = "yourusername/ubuntu2004"
     config.vm.box_version = "1.0.0"
   end

Run:

   vagrant up
   vagrant ssh

Clean up and delete:

   vagrant destroy -f

Conclusion

Creating and sharing a Vagrant box on Vagrant Cloud is straightforward once you understand the process. By following these steps, you can package a custom VM and make it available for others to use in their dev workflows. Whether you’re sharing a public box with the community or a private box with your team, Vagrant Cloud simplifies distribution.

For more advanced setups, consider using Packer to automate box creation. Happy Vagrant-ing!

Resources and Troubleshooting

Clean up unnecessary files before packaging to reduce the box size.
To update the box, create a new version (e.g., ‘1.0.1’) and repeat the version creation and upload process.
Vagrant Cloud Documentation for CLI commands.
Security NOTE: Avoid including sensitive data in the box. The default Vagrant SSH key is insecure; encourage users to replace it in production builds whenever possible.