A profile can be one of the following:

  • A Git repo or local directory with a profile.hcl and optionally a Brewfile and/or services.yml.
  • An HTTPS URL or file path to a profile.hcl

Creating a profile

A profile contains definitions for the types of projects, language runtimes, brew packages, and Docker containers you want to manage via mstrap.

The default profile lives at ~/.mstrap and is designed to be your local profile, specific to that machine. You may edit ~/.mstrap/profile.hcl, ~/.mstrap/Brewfile, ~/.mstrap/services.yml freely, however if you want to share configurations across machines, you may want to create a “manage profile”, which has its configuration stored in Git.

To create a new “managed profile”, you can simply git init a new repository with any one of the following files defined below.

See the Configuration page for more information about using the managed profile.


profile.hcl configures the packages and projects that will be managed by mstrap.

Many settings are optional, and if a project conforms to various conventions, few things will need to be specified for each project.

# This directive defines configuration of a runtime, such as packages that
# will be installed globally for any installed version of the relevant language
# runtime, or the default runtime version to use if none is specified by a project.
runtime "ruby" {
  # If this is omitted, the latest installed will
  # be used as the default/global version
  default_version = "2.7.1"

  package "bundle-audit" {}

runtime "node" {
  package "ember-cli" {}
  package "release-it" {}

runtime "python" {
  package "ansible" {
    # Optionally specify a specific version. Uses
    # the underlying package manager's semantics
    # for version constraints.
    version = "2.8"

# This directive defines a project that will be managed by mstrap
# The label argument is a machine-friendly, canonical name for the
# project. This should be unique and is required.
project "my-cool-project" {
  # A user-friendly display name for the
  # project. Required.
  name = "My Cool Project"

  # A hostname for the project.
  # Defaults to CNAME.localhost.
  hostname = "coolproject.localhost"

  # Path of the project (inside ~/src).
  # Defaults to the cname.
  path = "cool-project"

  # Port nginx should use to proxy to the project.
  # Optional, if you're using UNIX sockets.
  port = 5004

  # Git URI for cloning the project. Required.
  repo = "ssh://"

  # Git URI for the upstream of the project. Optional. Used for automatically
  # updating the project main branch with that of the upstream projects. Useful
  # for fork-based project workflows.
  repo_upstream = "ssh://"

  # Whether or not to run scripts-to-rule-them-all
  # like script/bootstrap or script/setup, if
  # they exist. Defaults to true.
  run_scripts = true

  # Name of the runtimes used. Generally to be
  # omitted, as runtimes will be detected automatically.
  runtimes = [

  # Specify an absolute NGINX upstream, rather
  # than using something inferred by configuration.
  upstream = null

  # Whether or not to configure NGINX to handle
  # websockets for this application.
  # Defaults to false.
  websocket = true

  # Whether or not this is a web project that
  # will be setup with NGINX. Can be omitted
  # and will be inferred by the presence of
  # other web-related properties.
  web = true

# An example of a project that will have most of its settings inferred
project "simple-rails-project" {
  name = "Simple Rails Project"
  port = 5000
  repo = "ssh://"


A Brewfile is a file used by homebrew-bundle, to automate the installation of various software via Homebrew, Homebrew Casks, and even the Mac App Store. mstrap creates a Brewfile for the default profile to setup some basic dependencies, but you can add onto it, or add your own via managed profiles.


This file is just a regular docker-compose.yml that you can use for configuring services that you can manage through mstrap and may be used by your mstrap managed projects.

This is not created by default. Usage of Docker-related features in mstrap will warn you if this is missing.