The Problem — vagrant box add does NOT work for Parallels
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.
Correct Parallels Box Structure
Step-by-Step — Correct Way to Package a Parallels VM
Step 1 — Prepare the Base OEL 8 VM in Parallels
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
Step 2 — Find the .pvm File on Your Mac
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
Step 3 — Create metadata.json
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
Step 4 — Create Vagrantfile for the Box
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
Step 5 — Copy the .pvm Bundle
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/
Step 6 — Package into .box File
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
Step 7 — Add Box to Vagrant Using metadata.json
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)
Step 8 — Test the Box
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
Summary — Why This Works
| Step | What it does | Why critical |
|---|---|---|
| metadata.json in box | Declares provider=parallels | Without this Vagrant rejects the box |
| Copy .pvm folder | Includes full Parallels VM bundle | .pvm is the actual VM — not just a disk image |
| tar -czf | Creates .box (tar.gz archive) | Vagrant box format is always tar.gz |
| box-metadata.json | Points vagrant box add to correct provider | Allows versioning and provider specification |
| vagrant box add metadata.json | Registers box with correct provider | Direct 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.