Skip to content

Components of BOSH

Before creating a new environment we recommend to learn the names of major components that will be installed, used and configured:


Command Line Interface (CLI)

The Command Line Interface (CLI) is the primary operator interface to BOSH. An operator uses the CLI to interact with the Director and perform actions on the cloud.

CLI is typically installed on a machine that can directly communicate with the Director's API, e.g. an operator's laptop, or a jumpbox in the datacenter.


The Director is the core orchestrating component in BOSH. The Director controls VM creation and deployment, as well as other software and service lifecycle events.

The Director creates actionable tasks:

  • By translating commands sent by an operator through the CLI
  • From scheduled processes like backups or snapshots
  • If needed to reconcile the expected state with the actual state of a VM

Once created, the Director adds these tasks to the Task Queue. Worker processes take tasks from the Task Queue and act on them.

Task Queue

An asynchronous queue used by the Director and Workers to manage tasks. The Task Queue resides in the Database.


Director workers take tasks from the Task Queue and act on them.

Cloud Provider Interface (CPI)

A Cloud Provider Interface (CPI) is an API that the Director uses to interact with an IaaS to create and manage stemcells, VMs, and disks. A CPI abstracts infrastructure differences from the rest of BOSH.

Health Monitor

The Health Monitor uses status and lifecycle events received from Agents to monitor the health of VMs. If the Health Monitor detects a problem with a VM, it can send an alert through notification plugins, or trigger the Resurrector.


If enabled, the Resurrector plugin automatically recreates VMs identified by the Health Monitor as missing or unresponsive. It uses same Director API that CLI uses.

Components used to store Director's persistent data


The Director uses a Postgres database to store information about the desired state of a deployment. This includes information about stemcells, releases, and deployments.


The Blobstore stores the source forms of releases and the compiled images of releases. An operator uploads a release using the CLI, and the Director inserts the release into the Blobstore. When you deploy a release, BOSH orchestrates the compilation of packages and stores the result in the Blobstore.


BOSH includes an Agent on every VM that it deploys. The Agent listens for instructions from the Director and carries out those instructions. The Agent receives job specifications from the Director and uses them to assign a role, or Job, to the VM.

For example, to assign the job of running MySQL to a VM, the Director sends instructions to the Agent on the VM. These instructions include which packages to install and how to configure those packages. The Agent uses these instructions to install and configure MySQL on the VM.

Components used for cross-component communication

Message Bus (NATS)

The Director and the Agents communicate through a lightweight publish-subscribe messaging system called NATS. These messages have two purposes: to perform provisioning instructions on the VMs, and to inform the Health Monitor about changes in the health of monitored processes.


The User Account and Authentication Server is primarily used as OAuth2 provider used to issue OAuth tokens. See more details.

Example component interaction

This example shows how components interact when creating a new VM.

Creating a new VM


  1. Through the CLI, the operator takes an action (e.g. deploy for the first time, scaling up deployment) which requires creating a new VM.
  2. The CLI passes the instruction to the Director.
  3. The Director uses the CPI to tell the IaaS to launch a VM.
  4. The IaaS provides the Director with information (IP addresses and IDs) the Agent on the VM needs to configure the VM.
  5. The Director updates the Agent running on the VM with the IP addresses and IDs.
  6. The Agent uses the IP addresses and IDs to configure the VM.