Last updated:
Quick answer: Add Oracle’s VirtualBox repository using a signed keyring, install VirtualBox and the Extension Pack, create a dedicated user in the vboxusers group, set that user in /etc/default/virtualbox, start vboxweb-service, then serve phpVirtualBox from Apache or Nginx to manage everything through a browser.
The appeal is straightforward: a headless server has no graphical interface, so without something like this you are limited to managing virtual machines entirely through VBoxManage on the command line. phpVirtualBox gives you a web interface that closely resembles the desktop VirtualBox Manager.
Read this first: is phpVirtualBox the right choice?
An honest caveat, because it will save you time. phpVirtualBox has not kept pace with VirtualBox releases. The original project stalled, and the versions available today are community forks that lag behind current VirtualBox. Matching versions between the two is the single most common source of frustration with this setup.
It is still perfectly usable if you want a familiar VirtualBox interface on a headless box. But consider the alternatives before you commit:
| Option | Good for | Trade-off |
|---|---|---|
| phpVirtualBox | A familiar VirtualBox UI in a browser | Lags behind VirtualBox releases, version matching is fiddly |
| VBoxManage (CLI) | Scripting, automation, complete reliability | No graphical interface at all |
| Cockpit + cockpit-machines | A maintained web UI, using KVM rather than VirtualBox | Different hypervisor, so existing VirtualBox VMs need converting |
| Proxmox VE | Serious multi-VM hosting | A whole platform, installed instead of plain Ubuntu |
If you are building something new on a dedicated machine, Proxmox or KVM with Cockpit is the more future-proof route. If you specifically need VirtualBox, carry on.
Step 1: Update the server and install build tools
sudo apt update && sudo apt upgrade -y
sudo apt install build-essential dkms linux-headers-$(uname -r) -yDKMS rebuilds VirtualBox’s kernel modules whenever the kernel updates. Without it, VirtualBox quietly stops working after a routine upgrade and reboot.
Step 2: Add Oracle’s repository
The old apt-key add method used in guides of this era is deprecated and no longer works on current Ubuntu. Use a signed keyring instead:
wget -O- https://www.virtualbox.org/download/oracle_vbox_2016.asc | \
sudo gpg --dearmor --yes --output /usr/share/keyrings/oracle-virtualbox-2016.gpgThen add the repository, which picks up your Ubuntu codename automatically:
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/oracle-virtualbox-2016.gpg] https://download.virtualbox.org/virtualbox/debian $(lsb_release -cs) contrib" | \
sudo tee /etc/apt/sources.list.d/virtualbox.listStep 3: Install VirtualBox
sudo apt update
sudo apt install virtualbox-7.1 -yIf that package is unavailable for your release, check what Oracle currently publishes:
apt-cache search virtualbox-7Confirm the install and note the exact version, which you need for the next two steps:
VBoxManage --versionStep 4: Install the Extension Pack
The Extension Pack adds USB 2.0/3.0 support and, importantly for headless use, VRDP remote display. Its version must match VirtualBox exactly.
cd /tmp
VBOX_VERSION=$(VBoxManage --version | cut -d 'r' -f 1)
wget "https://download.virtualbox.org/virtualbox/${VBOX_VERSION}/Oracle_VirtualBox_Extension_Pack-${VBOX_VERSION}.vbox-extpack"
sudo VBoxManage extpack install "Oracle_VirtualBox_Extension_Pack-${VBOX_VERSION}.vbox-extpack"Note that Oracle’s Extension Pack is free for personal and evaluation use but requires a licence for commercial deployment. Worth knowing before you put it on a company server.
Step 5: Create a dedicated VirtualBox user
sudo useradd -m -s /bin/bash vboxuser
sudo passwd vboxuser
sudo usermod -aG vboxusers vboxuserRunning the web service as a dedicated account rather than your own login keeps VM ownership tidy and limits what a compromise of the web interface could reach.
Check the kernel modules are loaded:
sudo systemctl status vboxdrvIf they are not, rebuild them:
sudo /sbin/vboxconfigStep 6: Install a web server and PHP
sudo apt install apache2 php php-common php-soap php-gd php-xml -yThe php-soap module is not optional. phpVirtualBox communicates with the VirtualBox web service over SOAP, and its absence is the usual cause of a blank page after login.
Step 7: Install phpVirtualBox
Download a release matching your VirtualBox major version from the phpVirtualBox project on GitHub, then:
cd /tmp
unzip phpvirtualbox-*.zip
sudo mv phpvirtualbox-* /var/www/html/phpvirtualbox
sudo chown -R www-data:www-data /var/www/html/phpvirtualboxCopy the sample configuration and edit it:
sudo cp /var/www/html/phpvirtualbox/config.php-example /var/www/html/phpvirtualbox/config.php
sudo nano /var/www/html/phpvirtualbox/config.phpSet the user credentials you created earlier:
var $username = 'vboxuser';
var $password = 'your_password_here';Step 8: Configure and start the VirtualBox web service
sudo nano /etc/default/virtualboxAdd:
VBOXWEB_USER=vboxuserThen start and enable the service:
sudo systemctl enable --now vboxweb-service
sudo systemctl status vboxweb-serviceThe username here must exactly match the account that owns the VMs. A mismatch produces a login page that accepts your details and then shows nothing, which is a confusing failure to diagnose.
Step 9: Log in and secure it immediately
Browse to http://your-server-ip/phpvirtualbox. The default credentials are admin / admin.
Change that password before you do anything else. Go to File, then Change Password, inside the interface. An admin/admin panel that can create and delete virtual machines is exactly what automated scanners look for.
Beyond the password, do not expose this interface to the open internet. Either restrict it by IP in your firewall:
sudo ufw allow from YOUR.IP.ADDRESS.HERE to any port 80Or, better, leave it closed entirely and reach it through an SSH tunnel:
ssh -L 8080:localhost:80 vboxuser@your-server-ipThen open http://localhost:8080/phpvirtualbox on your own machine.
Once you are in, the interface behaves much like desktop VirtualBox, and you can create and manage guests from anywhere.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Blank page after logging in | php-soap missing | sudo apt install php-soap, then restart Apache |
| “Could not connect to host” | vboxweb-service not running | sudo systemctl status vboxweb-service and start it |
| Login accepted but no VMs listed | VBOXWEB_USER does not own the VMs | Match the user in /etc/default/virtualbox to the VM owner |
| Version mismatch warning | phpVirtualBox older than VirtualBox | Use a phpVirtualBox release matching your VirtualBox major version |
| VirtualBox breaks after a kernel update | Modules not rebuilt | Install dkms, then run sudo /sbin/vboxconfig |
| Extension Pack refuses to install | Version does not match VirtualBox | Download the pack for your exact VirtualBox version |
Managing VMs without a web interface
If phpVirtualBox proves more trouble than it is worth, VBoxManage handles everything on its own:
# List all virtual machines
VBoxManage list vms
# Start a VM with no display attached
VBoxManage startvm "MyVM" --type headless
# Shut a VM down gracefully
VBoxManage controlvm "MyVM" acpipowerbutton
# See which VMs are currently running
VBoxManage list runningvmsFor scripted or automated setups this is genuinely more reliable, and it never suffers version-matching problems.
Frequently asked questions
Does this work on Ubuntu 24.04?
Yes. The repository line picks up your codename automatically, so the same steps apply to 24.04, 22.04 and Debian.
Do I need the Extension Pack?
Only for USB 2.0/3.0 passthrough and VRDP remote display. Basic headless VMs run without it, and skipping it avoids the licensing question entirely.
Can I access a VM’s screen remotely?
Yes, through VRDP, which the Extension Pack provides. Enable it per VM and connect with any RDP client.
Is VirtualBox a sensible choice for a server?
It works, but KVM is the more natural fit for Linux servers, being built into the kernel and generally faster. VirtualBox makes most sense when you already have VMs in that format or know the tooling well.
Why does it break after every kernel update?
VirtualBox needs kernel modules compiled against the running kernel. DKMS rebuilds them automatically, which is why it is installed in step 1.
Can I copy and paste between my computer and a VM?
That needs a desktop session. On a headless server you work through phpVirtualBox or a remote display, but with desktop VirtualBox you can enable the shared clipboard between host and guest.