Skip to content
VirtualBox API for Ruby
Failed to load latest commit information.
.document Initial commit to virtual_box. Nov 7, 2010
.gitignore Bumped dependencies. Sep 7, 2012
Gemfile Bumped dependencies. Sep 7, 2012
Gemfile.lock Bumped dependencies. Oct 17, 2012
README.markdown Refactored Net#if_name -> Net#name plus minor API improvements. Added… May 6, 2012
Rakefile WiP: TinyCore remix for integration-testing VirtualBox's DHCP and I/O… Apr 29, 2012
VERSION Version bump to 0.1.4 May 7, 2012
virtual_box.gemspec Regenerate gemspec for version 0.1.4 May 7, 2012



This gem is a Ruby API for VirtualBox, Sun's open-source virtualization software that supports Linux, Mac OS X, and Windows.


virtual_box is mainly intended to help out with testing. The snippet below shows a complete setup / teardown scenario.

setup do
    vdi_file = '/tmp/disk.vdi'
    @disk = VirtualBox::Vm::Disk.create :file => vdi_file,
                                        :size => 16 * 1024 * 1024
  iso_file = 'test/fixtures/tinycore/remix.iso'
  @net = => '', :netmask => '',
                             :dhcp => { :start_ip => '' }).add

  @vm =
      :board => { :ram => 256, :video_ram => 16, :os => :linux26 },
      :io_buses => [{ :bus => :ide,
                      :disks => [{ :file => iso_file, :port => 1 }] },
                    { :bus => :sata, :disks => [@disk] }],
      :nics => [{ :mode => :host, :chip => :virtual,
                  :net_name => }]).register

teardown do


Currently, the gem supports the following features:

  • VM creation and removal
  • VM start, and stop
  • Disk (VDI, VMDK, VHD) and DVD (ISO) images
  • NAT, bridged, host-only and internal networking
  • DHCP configuration for host-only and internal networks
  • VirtualBox version detection (OSE vs. regular)


The gem uses the VirtualBox CLI (command-line tools), so they must be installed and on the system's path. The gem is developed against the documentation for VirtualBox 4.

Development Dependencies

Running tests relies on a few command-line tools.

On Fedora, use the following command to install the packages.

sudo yum install -y advancecomp curl mkisofs p7zip p7zip-plugins squashfs-tools

On OSX, run the following command.

brew install advancecomp cdrtools curl p7zip squashfs


This gem makes some simplifying assumptions (rails people would say it is opinionated).

  • VM configuration XML file management is completely delegated to VirtualBox; the gem assumes and enforces the invariant that all XML files map to registered VMs

Contributing to virtual_box

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please do not mess with the Rakefile, version, or history.


Copyright (c) 2010-2012 Victor Costan. See LICENSE.txt for further details.

Something went wrong with that request. Please try again.