Vagrant OEL 8 DevOps · Parallels · macOS · Box Packaging

VagrantCorrect Way to Package a Parallels VM as Vagrant Box

The correct method to package an OEL 8 Parallels Desktop VM as a Vagrant box. Fix the vagrant box add error — create metadata.json, copy .pvm bundle and package correctly.

When you try to package and add a Parallels VM box the standard way, it fails:

BASH — What Fails
# THIS DOES NOT WORK FOR PARALLELS:
vagrant box add oraclelinux_custom oraclelinux.box

# Error you get:
# The box you attempted to add doesn't match the provider
# you specified. You specified "parallels" but the box
# is for "virtualbox" (or invalid format).

The reason is that Parallels boxes have a completely different internal structure compared to VirtualBox boxes. A Parallels box must contain a .pvm bundle (Parallels Virtual Machine) and a specific metadata.json file pointing to it. Simply running vagrant package or renaming a .box file does NOT create a valid Parallels box.

oraclelinux.box (tar.gz) ├── metadata.json — tells Vagrant: provider=parallels ├── Vagrantfile — base Vagrantfile embedded in box └── oraclelinux.pvm/ — Parallels VM bundle folder ├── config.pvs — VM config XML ├── config.pvs.backup └── Windows XP.hdd/ — Virtual disk ├── DiskDescriptor.xml └── *.hds files
BASH — Prepare Base VM
# In Parallels Desktop — create or use existing OEL 8 VM
# Make sure the VM is configured for Vagrant:

# 1. Set VM name (e.g. OEL8-Base)
# 2. Inside the OEL 8 VM, create vagrant user:
sudo useradd vagrant
echo "vagrant" | sudo passwd --stdin vagrant
echo "vagrant ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/vagrant
sudo chmod 440 /etc/sudoers.d/vagrant

# 3. Add Vagrant insecure public key
sudo mkdir -p /home/vagrant/.ssh
sudo chmod 700 /home/vagrant/.ssh
sudo curl -sSL https://raw.githubusercontent.com/hashicorp/vagrant/main/keys/vagrant.pub   -o /home/vagrant/.ssh/authorized_keys
sudo chmod 600 /home/vagrant/.ssh/authorized_keys
sudo chown -R vagrant:vagrant /home/vagrant/.ssh

# 4. Configure SSH
sudo sed -i "s/#UseDNS yes/UseDNS no/" /etc/ssh/sshd_config
sudo sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/" /etc/ssh/sshd_config
sudo systemctl restart sshd

# 5. Install Parallels Tools inside VM
# In Parallels menu: Actions → Install Parallels Tools
# Follow the installer

# 6. Clean up before packaging
sudo dnf clean all
sudo rm -rf /tmp/*
sudo rm -f /var/log/wtmp /var/log/btmp
sudo cat /dev/null > /home/vagrant/.bash_history
history -c
sudo shutdown -h now
BASH — Find .pvm File
# Parallels stores VMs in:
ls ~/Parallels/

# Find your OEL 8 VM bundle (.pvm folder)
ls ~/Parallels/ | grep -i oel
# Example: OEL8-Base.pvm

# Full path example:
# ~/Parallels/OEL8-Base.pvm
BASH — Create metadata.json
# Create a working directory for packaging
mkdir -p ~/vagrant-box-build/oel8-parallels
cd ~/vagrant-box-build/oel8-parallels

# Create metadata.json — this is the CRITICAL file
cat > metadata.json << EOF
{
  "provider": "parallels"
}
EOF

# Verify
cat metadata.json
BASH — Create Box Vagrantfile
# Create base Vagrantfile embedded in the box
cat > Vagrantfile << EOF
# Base Vagrantfile for OEL 8 Parallels box
Vagrant.configure("2") do |config|
  config.vm.provider "parallels" do |prl|
    prl.update_guest_tools = false
    prl.check_guest_tools  = false
  end
end
EOF
BASH — Copy .pvm Bundle
# Copy the entire .pvm folder into your build directory
cp -r ~/Parallels/OEL8-Base.pvm ~/vagrant-box-build/oel8-parallels/

# Your directory should now look like:
ls -la ~/vagrant-box-build/oel8-parallels/
# metadata.json
# Vagrantfile
# OEL8-Base.pvm/
BASH — Create .box File
cd ~/vagrant-box-build/oel8-parallels

# Package everything into a .box file (tar.gz format)
tar -czf ../oraclelinux8.box metadata.json Vagrantfile OEL8-Base.pvm

# Check the box file was created
ls -lh ../oraclelinux8.box

# Verify contents
tar -tzf ../oraclelinux8.box | head -20
BASH — Add Box via Metadata JSON
# Create a metadata JSON file that points to your box
# This is needed for correct provider registration

cat > ~/vagrant-box-build/box-metadata.json << EOF
{
  "name": "oraclelinux8-parallels",
  "description": "Oracle Enterprise Linux 8 for Parallels",
  "versions": [
    {
      "version": "1.0.0",
      "providers": [
        {
          "name": "parallels",
          "url": "file:///Users/$(whoami)/vagrant-box-build/oraclelinux8.box"
        }
      ]
    }
  ]
}
EOF

# Add box using the metadata JSON (correct method for Parallels)
vagrant box add ~/vagrant-box-build/box-metadata.json

# Verify box was added
vagrant box list
# Should show:
# oraclelinux8-parallels (parallels, 1.0.0)
BASH — Test Custom Box
# Create a test project
mkdir -p ~/vagrant-test-parallels && cd ~/vagrant-test-parallels

# Create Vagrantfile using your custom box
cat > Vagrantfile << EOF
Vagrant.configure("2") do |config|
  config.vm.box = "oraclelinux8-parallels"

  config.vm.provider "parallels" do |prl|
    prl.name   = "OEL8-Test"
    prl.memory = 2048
    prl.cpus   = 2
    prl.update_guest_tools = false
  end
end
EOF

# Start VM with Parallels
vagrant up --provider=parallels

# SSH in
vagrant ssh

# Verify OEL 8
cat /etc/oracle-release
exit
StepWhat it doesWhy critical
metadata.json in boxDeclares provider=parallelsWithout this Vagrant rejects the box
Copy .pvm folderIncludes full Parallels VM bundle.pvm is the actual VM — not just a disk image
tar -czfCreates .box (tar.gz archive)Vagrant box format is always tar.gz
box-metadata.jsonPoints vagrant box add to correct providerAllows versioning and provider specification
vagrant box add metadata.jsonRegisters box with correct providerDirect box add fails — must use metadata JSON
⚠ Warning: Never use vagrant package to create a Parallels box — it only works for VirtualBox. Always follow the manual tar.gz method shown above for Parallels.
Once the box is added correctly, it works exactly like any Vagrant box — vagrant up, vagrant ssh, vagrant snapshot, all commands work normally.