Run packages

Habitat packages used to start services are run under the Habitat supervisor. At runtime, you can join supervisors together in a service group running the same topology, send configuration updates to that group, and more. You can also export the supervisor together with the package to an external immutable format, such as a Docker container.

Running single packages for testing

Packages can be tested in the interactive studio environment or natively on a host machine running Linux.

When entering an interactive studio, a supervisor is started for you in the background. To run packages inside of this supervisor:

  1. Build your package inside an interactive studio. Do not exit the studio after it is built.
  2. To start your service in the running supervisor, type hab sup start yourorigin/yourname, substituting the name and origin of the package you built in step 1. Your service should now be running.

Because the supervisor is running in the background, you will not see the supervisor output as you start your service. However you can use the slog (supervisor log) command that will stream the tail of the supervisor output.

If your host machine is running Linux, do the following to run your packages:

  • Add the hab user and group.

    sudo adduser --group hab
    sudo useradd -g hab hab
  • Run the hab CLI as root.

    sudo hab start yourorigin/yourname

Running packages in any environment

The hab program can also be installed on servers. It will retrieve the necessary components (like the current release of the supervisor) in order to run packages. Thus, you can start the supervisor on any compatible system. As the supervisor can run more than one service (for more details, see the multiple services page), only one is necessary per host.

To start the supervisor, you can write an init script or a systemd unit file. For example, for systemd:

  Description=The Habitat Supervisor

  ExecStart=/bin/hab sup run


Next use hab service load to load one or more services into the supervisor for permanent supervision. Using the example from above:

  sudo hab service load yourorigin/yourname

Section details

This section is divided into the following areas:

  • Service groups: Defines service groups and how to join them.
  • Topologies: Explains topologies in Habitat and how to join them.
  • Configuration updates: Learn how to apply configuration updates to multiple services in a service group.
  • Upload files: Learn how to upload files to multiple services in a service group.
  • Security: Describes how to encrypt communication between supervisors, and between users and service groups.
  • Binding: Learn how to bind to unknown service group names at runtime.
  • Update strategy: Describes how the supervisor and its peers within a service group should respond when a new version of a package is available.
  • Multiple services: Lean how to run multiple services with one supervisor.
  • Export packages: Learn how to export packages into multiple external, immutable runtime formats and work with container cluster managers like Kubernetes and Mesos.
  • Monitor services through the HTTP API: Discover how to use the HTTP API to retrieve census, status, and health information from your running services.