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

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 1396d7877204e630b9e77ae680f492d26607461d
  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
  5. Optionally, set up a local route for bosh ssh command

    $ sudo route add -net # Mac OS X
    $ sudo route add -net gw # Linux
    $ route add  # Windows
  6. In case you need to SSH into the Director VM, see Jumpbox.

  7. In case VirtualBox VM shuts down or reboots

    To bring back the Director on the VM 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