This blog will be split into multiple posts. In this post, we will be introduced to Habitat, discuss its concepts, and learn how to set up Habitat.

What is Habitat?

Back in June 2016 Chef launched Habitat, a new open source project for automatic applications. Habitat describes itself as a new approach to deploying applications called “application automation”. As the name Habitat suggests, the automation comes packaged with the application and travels with it regardless of where it is deployed, so the unit is both the application and automation. Basically, instead of deploying a whole application, you deploy them as packages that are managed. The goal of Habitat was to make the application the owner of all the automation it would need for its life.

Currently Habitat is available for Mac OS X, Windows, and Linux. If you are using Mac OS X or Windows, you will also need to have Docker installed.

Habitat Concepts

Habitat is comprised of a plan and build system, a supervisor, an HTTP interface on that supervisor to report package status, a depot, a communication model for disseminating rumors through a supervisor ring, and many other components. See below for details:


The package contains your entire Habitat (the application, runtime, dependencies, and any configuration data). Packages are made of four components:

  1. Origin: The name that defines a set of packages. i.e. core

  2. Name: The name of the application i.e. myapp

  3. Version: The version number of the package, as defined by the author

  4. Release: This is a unique ID that Habitat gives a person that it based on the timestamp. For example, if I made a version at the time this blog was written, it would be “201610131726”.

A package can be identified by the origin and name. i.e. core/myapp or by all four components core/myapp/1.0/201610131726. If using the former, the version and ID are assumed to be the latest versions.


The supervisor manages the life cycle of the app. It has two primary responsibilities: keep the app running and reconfigure it as needed. There can be more than one supervisor in a habitat (in fact, there can be thousands), and supervisors can communicate with other supervisors in deployment to provide healthy monitoring and other status messages. The supervisors coordinate their topology (leader/follower, for example), their update strategy (deploy new versions one at a time, etc.), their security (we need this ssl cert, these secrets), etc.


The supervisors run a network called a ring (which is more analogous to a peer-to-peer network and not a circular ring). Rings can be large and contain thousands of supervisors if they need to.


The director supervises the supervisors running on a machine. It will restart child processes when it detects that they fail.

Habitat service

The Habitat service is a running supervisor with the application or service of the package running inside it.


A plan is a shell script where you put in information about what your package contains, how it is built, and how it can be configured. Essentially, it has the instructions on how to download, compile, and install the package. The plan will be placed in a bash script called


The Habitat Studio is a environment that is set up so you can develop, build, and package software in a clean environment. All tools and dependencies are built in the studio from the Habitat packages, so the studio environment only pertains to what you need.

Other Concepts

More information on these concepts can be found on the Habitat docs.

Setting up your Habitat environment

Now we’ll learn how to set up Habitat on our local machine.

First, you need to download Habitat onto your local machine. If you have a Mac (like I do), you will also need to download Docker (instructions are on the same page). This will download the hab command-line interface onto your machine. This will allow it to download other components as needed.

Next, we’ll need to set up our environment and integrate hab into our shell. For more information, you can refer to the Habitat docs.

First, open your shell and change the directory to the directory where you want the hab CLI to be (I set mine to my home directory). Copy the file you downloaded from the Habitat website into a new directory that you’ll make called ~bin, like this:

cd ~
mkdir -p ~/bin
cp path/to/your/download/hab ~/bin

Next, add this location to your PATH environmental variable by typing this line:

export PATH=$PATH:~/bin

Now, run hab setup and follow the instructions that it gives you.

You will be asked to create a new origin, like we discussed above. You can give this whatever name you want.

You can also provide a Github personal access token so you can upload packages and share them in the Habitat community. The Github personal access token will require user:email and read:orgs scopes, which determine features based on team membership in Habitat. If you would like to change this later, you can always rerun hab setup and change your settings.

That’s it! Try typing hab into your terminal. If everything is set up correctly you should see something like this:

hab terminal

Next Steps

In the next post, we will learn how to create a plan, build an artifact, and learn how to configure it. Stay tuned until then!