BOSH Lite v2 is a Director VM running in VirtualBox (typically locally). It is managed via CLI v2. Internally CPI uses containers to emulate VMs which makes it an excellent choice for:

  • General BOSH exploration without investing time and resources to configure an IaaS
  • Development of releases (including BOSH itself)
  • Testing releases locally or in CI


Follow below steps to get it running on locally on VirtualBox:

  1. Check that your machine has at least 8GB RAM, and 100GB free disk space. Smaller configurations may work.

  2. Install CLI v2

  3. Install VirtualBox

    Known working version:

    $ VBoxManage --version

    Note: If you encounter problems with VirtualBox networking try installing Oracle VM VirtualBox Extension Pack as suggested by Issue 202. Alternatively make sure you are on VirtualBox 5.1+ since previous versions had a network connectivity bug.

  4. Install Director VM

    $ git clone ~/workspace/bosh-deployment
    $ mkdir -p ~/deployments/vbox
    $ cd ~/deployments/vbox

    Below command will try automatically create/enable Host-only network (details) and NAT network ‘NatNetwork’ with DHCP enabled (details).

    $ bosh create-env ~/workspace/bosh-deployment/bosh.yml \
      --state ./state.json \
      -o ~/workspace/bosh-deployment/virtualbox/cpi.yml \
      -o ~/workspace/bosh-deployment/virtualbox/outbound-network.yml \
      -o ~/workspace/bosh-deployment/bosh-lite.yml \
      -o ~/workspace/bosh-deployment/bosh-lite-runc.yml \
      -o ~/workspace/bosh-deployment/jumpbox-user.yml \
      --vars-store ./creds.yml \
      -v director_name="Bosh Lite Director" \
      -v internal_ip= \
      -v internal_gw= \
      -v internal_cidr= \
      -v outbound_network_name=NatNetwork
  5. Alias and log into the Director

    $ bosh alias-env vbox -e --ca-cert <(bosh int ./creds.yml --path /director_ssl/ca)
    $ export BOSH_CLIENT=admin
    $ export BOSH_CLIENT_SECRET=`bosh int ./creds.yml --path /admin_password`
  6. Confirm that it works

    $ bosh -e vbox env
    Using environment '' as '?'
    Name: ...
    User: admin
  7. Optionally, set up a local route for bosh ssh commands or accessing VMs directly

    $ sudo route add -net # Mac OS X
    $ sudo ip route add via # Linux (using iproute2 suite)
    $ sudo route add -net gw # Linux (using DEPRECATED route command)
    $ route add  # Windows

Deploy example Zookeeper deployment

Run through quick steps below or follow deploy workflow that goes through the same steps but with more explanation.

  1. Update cloud config

    $ bosh -e vbox update-cloud-config ~/workspace/bosh-deployment/warden/cloud-config.yml
  2. Upload stemcell

    $ bosh -e vbox upload-stemcell \
      --sha1 1dad6d85d6e132810439daba7ca05694cec208ab
  3. Deploy example deployment

    $ bosh -e vbox -d zookeeper deploy <(wget -O-
  4. Run Zookeeper smoke tests

    $ bosh -e vbox -d zookeeper run-errand smoke-tests


  • In case you need to SSH into the Director VM, see Jumpbox.
  • In case VirtualBox VM shuts down or reboots, you will have to re-run create-env command from above. (You will have to remove current_manifest_sha line from state.json to force a redeploy.) The containers will be lost after a VM restart, but you can restore your deployment with bosh cck command. Alternatively Pause the VM from the VirtualBox UI before shutting down VirtualBox host, or making your computer sleep.
  • If you are looking for the original Vagrant-based BOSH Lite, please refer to cloudfoundry/bosh-lite’s README.

Contribute changes to this page