What the solution is

It is a Homebrew-first software provisioning framework for managed macOS devices.

At a high level, it standardizes software installation around:

• a stable Homebrew execution path
• a dedicated non-interactive runtime user
• a small set of reusable installation primitives
• Brewfiles for declarative software sets
• an optional device management platform as the execution layer, not the logic layer

The core idea is not “everything must be installed with Homebrew.” It is:

standardize the provisioning model, with Homebrew as the default path and reusable exceptions for edge cases.

What problems it is trying to solve

1. Fragmented software setup

Right now, software provisioning happens through a mix of:

• inconsistent device management scripts
• App Store deployments
• one-off GitHub scripts
• ad hoc Homebrew usage
• manual installs

That creates drift in both behavior and maintenance.

2. Inconsistent developer environments

During:

• onboarding
• device upgrades
• loaner use
• rebuilds after a machine change

engineers end up manually reconstructing parts of their environment.

3. Fragmented setup knowledge

A lot of setup knowledge lives in:

• Slack threads
• personal notes
• tribal workflows
• one-off documentation

So even when the knowledge exists, it is not reproducible.

4. Inconsistent software lifecycle behavior

Some apps behave differently depending on distribution source.

Examples previously called out:

• Slack via App Store not updating reliably
• Tailscale via App Store not behaving reliably in our environment

So the problem is not only “how software is installed,” but also “which distribution path produces the correct result.”

5. Maintenance burden

Without shared primitives, similar install tasks get solved multiple different ways, which leads to:

• duplicated logic
• harder troubleshooting
• harder auditing
• more snowflake scripts over time

How it works

The system has a few layers.

Bootstrap layer

Bootstrap sets up the environment once so later installs can happen consistently.

It does things like:

• create a hidden runtime user (falstaff)
• install Command Line Tools
• install Homebrew from the official package release
• write a stable wrapper at /usr/local/bin/brew
• install scoped support files like sudoers rules

This is what makes Homebrew callable reliably in a non-interactive context.

Provisioning layer

After bootstrap, software gets installed through a small set of primitives:

• Homebrew for most software
• direct .pkg install from URL
• latest GitHub .pkg release install

These are not app-specific scripts. They are general installation strategies.

Definition layer

Brewfiles define software sets declaratively.

That supports three levels:

• managed baseline maintained by IT
• shared team/role Brewfiles in source control
• personal local Brewfiles for individual customization

That turns setup from “follow these steps” into “apply this definition.”

Execution layer

A device management platform can:

• trigger the scripts
• schedule them
• scope them to devices

But the platform does not own the actual provisioning logic. The logic lives in the scripts and Brewfiles.

That makes the model portable.

The philosophy behind the approach

There are a few explicit design choices underneath it.

Homebrew-first, not Homebrew-only

Homebrew is the default because it aligns with how engineers already work, but it is not treated as the only valid mechanism.

If a .pkg or GitHub release produces the more correct system state, that path is used instead.

Standardize the model, not every app

The goal is not to force every application into one installation mechanism.

The goal is to make the orchestration consistent:

• same execution model
• same primitives
• same general policy structure
• same mental model for operators

Mechanical, readable code

The scripts are intentionally straightforward.

They are meant to be:

• easy to read
• easy to reason about
• maintainable by people with different skill levels

This is not “simple because unfinished.” It is simple by design.

The script is the documentation

I wanted the implementation to be legible enough that the code itself explains the behavior.

That reduces the gap between docs and reality.

Ecosystem-native

The approach stays close to:

• macOS-native tools
• shell
• Homebrew
• standard utilities

That minimizes added dependencies and keeps the runtime requirements low.

Preserve upstream errors

Instead of wrapping everything in custom error messages, the scripts largely let tools like:

• brew
• curl
• installer
• softwareupdate

surface their own output.

That makes troubleshooting easier because the operator sees the real error and can search for it directly.

What the primary brew wrapper does

The wrapper is the main abstraction point.

It lives at:

/usr/local/bin/brew

Its job is to ensure that brew always runs the same way, regardless of who triggered it.

Example structure:

!/bin/sh

brew() {
    NONINTERACTIVE=1 HOMEBREW_DOWNLOAD_CONCURRENCY=auto /usr/bin/sudo -u falstaff -i /opt/homebrew/bin/brew "$@"
}

brew "$@"

What that gives you

• brew always runs as the dedicated runtime user
• it does not depend on the currently logged-in user
• it runs non-interactively
• scripts and operators both have one stable entry point

Example usage

Install a cask:

/usr/local/bin/brew install --cask google-chrome

Install a formula:

/usr/local/bin/brew install jq

Apply a Brewfile:

/usr/local/bin/brew bundle --file "/private/tmp/CommonApps-brewfile"

That wrapper is the reason the rest of the system can treat Homebrew as a stable operational interface.

How the bootstrap script is used

Bootstrap is both:

• a one-time environment initializer
• a source of reusable primitives

That dual role is important.

As an initializer

Run bootstrap first to establish the runtime:

• create runtime identity
• install prerequisites
• install Homebrew
• create wrapper
• install support config

After that, subsequent scripts can safely rely on the environment.

As a primitive library

The functions inside bootstrap can also be reused independently in other scripts.

That means the value of bootstrap is not only its one-time side effects, but also the reusable patterns it defines.

Independent primitives inside bootstrap

These are the major reusable pieces.

1. createHiddenAdminUser()

Purpose:

• create the dedicated runtime identity used for non-interactive Homebrew execution

Example:

createHiddenAdminUser "$(/usr/bin/uuidgen)"

This is mostly bootstrap-specific, but it is still a discrete primitive.

2. installCommandLineTools()

Purpose:

• install Apple Command Line Tools before other provisioning steps

Example:

installCommandLineTools

This can be reused anywhere you need to ensure the machine has that baseline.

3. installPkgFromURL()

Purpose:

• install a .pkg from a direct URL

Example:

installPkgFromURL "https://example.com/MyApp.pkg"

This is one of the most reusable primitives in the whole model.

Use it when:

• a stable package URL exists
• the package is the correct distribution
• you want predictable package-based installation

4. getGithubLatestPkgURL()

Purpose:

• resolve the latest .pkg asset from a GitHub release

Example:

PKG_URL="$(getGithubLatestPkgURL root3nl SupportApp)"

This is useful when the canonical upstream distribution is GitHub releases.

It decouples “find the package” from “install the package.”

5. Composing the two package primitives

This is where the model becomes powerful.

Example:

SUPPORT_APP_PKG_URL="$(getGithubLatestPkgURL root3nl SupportApp)"
installPkgFromURL "${SUPPORT_APP_PKG_URL}"

That is a general pattern, not a one-off hack:

1. resolve package source
2. install package

6. installFile()

Purpose:

• write content to a file and set the mode consistently

Example:

installFile "${BREW_WRAPPER_CONTENT}" "/usr/local/bin/brew" 755

This is also a real primitive.

It is useful for:

• wrapper scripts
• config fragments
• support files
• sudoers drop-ins

Because it centralizes a common operation: write content → apply mode.

Examples of installFile() in practice

Writing the sudoers file

installFile "${BREW_INSTALLER_SUDO_RULES_CONTENT}" "/etc/sudoers.d/brew-cask-installer" 0440

Writing the brew wrapper

installFile "${BREW_WRAPPER_CONTENT}" "/usr/local/bin/brew" 755

So installFile() is not incidental. It is part of the shared provisioning substrate.

How the pieces fit together

A clean way to think about the system is:

Step 1: bootstrap the machine

This establishes:

• runtime user
• prerequisites
• Homebrew
• wrapper
• supporting config

Step 2: provision software using shared primitives

Use:

• /usr/local/bin/brew for standard installs
• installPkgFromURL() for direct packages
• getGithubLatestPkgURL() + installPkgFromURL() for GitHub-hosted packages

Step 3: define software sets declaratively

Use Brewfiles for:

• baseline apps
• role-based apps
• personal overlays

That gives you a system that is both operational and reproducible.

Why this scales

This approach scales because the logic is not tied to a specific device management tool.

With a management platform:

• it executes and schedules the scripts

Without one:

• the same scripts and Brewfiles still work locally

So the portable part is not the MDM integration. The portable part is the provisioning model itself.

The core shift in one sentence

The solution turns software setup from a mix of app-specific scripts and tribal knowledge into a Homebrew-first, primitive-based provisioning model with reproducible environment definitions.