node package manager



A simple utility for managing the virtual machine lifecycle


Vagabond is a tool to manage the lifecycle of virtual machines. It is useful in environments where a build environment may not completely match the deployment environment. Vagabond makes it easy to install a virtual machine for testing from the command line or an automated script. Vagabond takes it's configuration information from a properties file suitable for inclusion into a source code control system.

In short, Vagabond makes dealing with virtual machines a little easier on developers.


Vagabond is dependent on Oracle's VirtualBox system, so it should be installed before you install Vagabond. You should also ensure that the VBoxManage utility is in your path before executing Vagabond commands.

To install Vagabond, use NPM:

    sudo npm install -g vagabond

Simple Example

Before starting a Vagabond-managed virtual machine, you should create a configuration file with the "init" command:

    vagabond init

This will create the file vagabond.json with a few default configuration options. Here's an example:

      "name": "66e3efa7e9143ddb_helium",
      "hostname": "helium",
      "addr": "",
      "ova": "",
      "user": {
        "name": "<username>",
        "ssh": "ssh-rsa AAAAB3N ..."

If Vagabond can determine your username and find your SSH public key, it will fill in those values automagically. If it can't, you should add them yourself. If you plan to use Samba file sharing or you don't want to use public-key authentication with SSH, you must add a passwd entry to the user object, so it looks something like this:

    "user": {
        "name": "<username>",
        "passwd": "IAmABadPassword",
        "ssh": "ssh-rsa AAAAB3N ..."

After editing the vagabond.json file, you're ready to create a virtual machine instance, launch it and log in with these commands:

    vagabond create
    vagabond launch
    vagabond user
    ssh `vagabond ip`

The commands listed above create a virtual machine, start the virtual machine, create the user account defined in the vagabond.json file and ssh to the virtual machine. Once you're finished with the virtual machine, you can destroy it with these commands:

    vagabond shutdown
    vagabond destroy

You can specify multiple commands with a single instance, like this:

    vagabond create launch user; \
      `vagabond ssh` "npm install foo; cd node_modules/foo/test; ./test"; \
      vagabond shutdown destroy

Command Line Options

init - Create a skeletal init file

This command creates a skeletal vagabond.json file. You should do this once before using other Vagabond commands.

create - Create a virtual machine instance

This command uses the VirtualBox appliance file specified in the configuration file to create a new virtual machine instance. If the appliance file is not found in the local cache (in the ~/.vagabond directory) it will download a local copy.

launch - Starts a virtual machine instance

This command starts a virtual machine and waits for the OpenSSH service in the virtual machine to start.

user - Creates a user in the virtual machine

This command creates a user account in the virtual machine using parameters found in the configuration file.

ip - return the ip address of the virtual machine's internal network adapter

This command echos the IP address of the virtual machine's internal network adapter. Example:

    ssh `vagabond ip`

ssh - return a ssh command to connect to the virtual machine

When connecting to a machine via ssh, it will cache that machine's server public key in the ~/.ssh/known_host file. New server keys are generated for each machine created, which will lead to stale key fingerprints in the known_host file. This command echos a ssh command that ignores the known_host file when connecting to the virtual machine. Unix users can use it like this:

    `vagabond ssh`

shutdown - shutdown a virtual machine

This command shuts down a virtual machine and waits for it to completely stop.

destroy - destroy the virtual machine instance

This command destroys the virtual machine instance specified in the config file.