developer workstation provisioner for macOS
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Devbook logo

A developer workstation provisioner for macOS powered by Ansible.


  • Dependencies: sh <(curl -sL for XCode CLI tools & Ansible
  • Installer:
    • Full (~1 hour): sh <(curl -sL
    • Partial (~0.5 hour): sh <(curl -sL
      • Add -k option for a SSH key install (e.g. sh <(curl -sL -k
    • (or clone the repo & run ./ & ./ if you don't trush me)


Devbook contains the following features (not exhaustive, see default.config.yml for the full manifest):


There are 3 config areas: override, devbook extension, & task/role.


If you want to set your own custom config it's easy to override defaults. Put a config.yml file into the Devbook repo and its values will be used instead of the defaults. Alternatively, adding a HTTP url param to ./ (or its curlsh equivalent) will retrieve the config file from the URL and use it as the config.yml.


  • Override the dotfiles_* values to specify the dotfiles repo & files you want to mount into your $HOME dir.
  • Override the prv_* values to specify the SSH-key protected repo & sensitive files you want to mount into your $HOME dir.
  • Specify the Homebrew packages/casks in homebrew_installed_packages/homebrew_cask_apps.
  • Specify custom mas_* values to customize your own App Store config.
  • Add various packages specified for the extra-packages task.
  • Add your own custom .macos file for your personal macOS system/app preferences.

Devbook Extension

Devbook has a few other extensible bits.


Upon completion, Devbook will look inside $HOME/.devbook/ for subdirs that have for execution. If you're familar with Ansible & Shell scripting, you can provide your own custom Ansible playbooks/roles & scripts needed to provision personal projects, client projects, or various role-based tools you need (e.g. you might need to provision a suite of design tools or DB developer tools).

To get started make sure prv_repo (or dotfiles_repo) has a mounted .devbook dir and subdirs with

Custom Notes

If you have any post-provision steps that might require manual steps (e.g. enabling FileVault, manual app install, etc.) you can drop them into After Devbook completes, it will print the contents out to the console after installation.


If you're familar with Ansible's tag system, you can tell Devbook to skip certain tags associated with tasks/roles in a .devbook.skip file (inside in the repo directory). The file contains a line-delimited list of tags to skip (run ansible-playbook main.yml --list-tags to see the list of Devbook tags.


The best laid schemes o' mice an' men...

I've found macOS provisioning prone to all kinds of problems (various types of app installers, a huge selection of open source tools, a consumer-oriented OS that's designed to abstract the technical bits). Don't be suprised at hiccups (I'm looking at you java8 Homebrew).

Luckily, Ansible is a great tool here. it's designed to be idempotent; you can run it over-and-over again without breaking things.

As Devbook runs through its playbook, it will tag its progress (in .devbook.tags). Running ./ after failure will skip completed tags and resume where it left off. If you provision a large tool chain expect: failures in package downloads and other unforseen problems.

If you hit any other issues, post it over here.


A shout out to geerlingguy & mathiasbynens which I based my work on. I pulled much cool stuff from these repos: geerlingguy/mac-dev-playbook & mathiasbynens/dotfiles

If you like to do testing, this repo is good for bootstrapping your own VirtualBox macOS image so you don't trash your current configuration.