Running VirtualBox Guest VMs In Headless Mode

If you are new to VirtualBox, you might not be aware that you can run your guest VMs without having a console window to them on your desktop.  IOW, run your guest VMs in the background and unseen.  This is called headless mode.  I’ll show you how to do that and a little more.

In headless mode, your guest VMs run in the background and you have the option to connect to them using the RDP protocol should you need a console to them.  This is great for uncluttering your desktop particularly if you run many guest VMs and you don’t care to see their console.  I have one server where I normally run at least five guest VMs at all times.  Headless mode is great when you need to log  into your host server remotely using ssh and start a guest VM.  This can be handy if you are on the road, away from your server.

Here is an example to demonstrate some common tasks.

Log into your host server using ssh.  Get a list of all VMs.

$ VBoxManage list vms

Start a guest VM named mywiki with RDP enabled and listening on port 3390.  If you plan to run multiple guest VMs in headless mode with RDP enabled, you will need to choose a unique port for each to listen on.  If you don’t specify a port, the default port is 3389.

$ nohup VBoxHeadless -s mywiki -v on -p 3390 &

Now if you want to check that your guest VM is among your running VMs

$ VBoxManage list runningvms

If you should need to connect to the console on that running VM named mywiki.  Lets assume it’s IP address is  We are going to use rdesktop, which is a good RDP client found in most linux distros.

$ rdesktop -g 1024x768 -a 16 -5 &

That should open up an nice 1024×768 window to your guest VM.  If the resolution 1024×768 is too big for you, then adjust the size to fit your needs.  The rdesktop settings “-a 16 -5” use a 16bit color depth and RDPv5.  Those settings work well for me and look good.

To view the properties of your VM use the showvminfo option.  This is handy if you want to connect your RDP client to a running VM and you don’t remember which port your VM is listening on.

$ VBoxManage showvminfo mywiki

Ok, now lets assume you have a rogue guest VM that want to shut-down and it is not responding to your request for a normal orderly shut-down.  You can power it off using VBoxManage.

$ VBoxManage contolvm mywiki poweroff

One of the things I love about VirtualBox is the amount of control you have from the cmdline.  Pretty much anything you can do from the management console can be done from the cmdline.  That is great especially if you enjoy writing scripts and want to automate some of these VirtualBox tasks.

Hopefully this will be enough to get you going.

6 thoughts on “Running VirtualBox Guest VMs In Headless Mode

  1. I have an Ubuntu server running fine with virtualbox in console mode, but when I start the first VM with the VBoxHeadless command I can’t return to the console prompt for startting a new VM. Please can you tell me how can I return to the console command prompt I was looking for some commands but I found nothing… 😦 . Thanks very much.

    • Sorry, I wasn’t clear. You should run that command as a background process. You will be returned to the cmd prompt again. You can do this for any command that you want to run in the background. Also if you start a command in the foreground, and want to move it to the background, you can hit ‘ctrl-z’ then type bg then hit ‘return’.

      nohup VBoxHeadless -s mywiki -v on -p 3390 &

  2. Thanks for the article.

    Strangely the GUI didn’t offer me to shut down my headless vm (which was not accessible in another way). Only the controlvm poweroff command worked.

    • Consider that In most headless environments you have little more than a minimal OS install on the host system and a cmdline, no GUI. The recommended procedure to shutdown any vm, especially a headless one, is to logon to the vm and initiate the appropriate shutdown procedure for your guest OS. For my linux vms I logon to them and then run “shutdown -h now”. I only use the controlvm poweroff if my vm is in a bad state or not responding to my logon attempts.

  3. Very useful article and very well explained. Thanks for the tip on running vms in the background.
    There’s a small typo (“contolvm” instead of “controlvm”) in the command to poweroff a vm.

  4. Your style is unique in comparison to other people I have read stuff
    from. Thank you for posting when you’ve got the opportunity, Guess I’ll just bookmark this page.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s