Verify Your Baseline: Xcode Command Line Tools
Before touching Homebrew, install the Xcode Command Line Tools. They provide clang, make, git, and the macOS SDK headers that most compiled packages depend on. Apple ships these separately from Xcode to keep the download size manageable.
Run the install command and wait for the GUI prompt, or drive it non-interactively:
On a fresh Sequoia install this takes 3-8 minutes. Verify the result:
You want clang 16 or higher. If you see an older version, your CLT installation may be stale - delete /Library/Developer/CommandLineTools and reinstall. Do not install the full Xcode IDE unless you are doing iOS or macOS app development; the CLT package is sufficient for all server-side and DevOps tooling.
# Interactive install
xcode-select --install
# Non-interactive (useful in provisioning scripts)
sudo xcode-select --switch /Library/Developer/CommandLineTools
# Verify
xcode-select -p
clang --version
git --versionInstall Homebrew and Understand the ARM Layout
Homebrew on Apple Silicon installs to /opt/homebrew, not /usr/local. This is intentional: it avoids conflicts with any Intel-era tooling and keeps SIP-protected paths clean. On an Intel Mac you still get /usr/local. Know which you are on:
The official install script handles both architectures automatically. Run it as a normal user - it will sudo when it needs to:
After install, Homebrew prints an eval block. Add it to your shell profile now, not later - everything downstream depends on PATH being correct:
On ARM, the eval line is /opt/homebrew/bin/brew shellenv. On Intel it is /usr/local/bin/brew shellenv. Use the dynamic form above so the same dotfile works on both architectures.
Run `brew doctor` immediately. On a clean Sequoia install you should see 'Your system is ready to brew.' Any warnings about PATH ordering need to be resolved before you proceed - a misordered PATH is the root cause of about 60% of 'wrong version is running' bugs we have diagnosed on Mac dev machines.
# Identify architecture
uname -m
# arm64 = Apple Silicon, x86_64 = Intel
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Add to ~/.zprofile (evaluated at login)
echo 'eval "$($(brew --prefix)/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
# Confirm
brew --version
brew doctorConfigure Zsh Properly Before Installing Anything Else
macOS ships Zsh 5.9 as the default shell. Do not replace it with a Homebrew Zsh unless you have a specific reason - the system Zsh is fine and avoids the complication of /etc/shells registration.
Zsh uses two separate startup file chains: login shells read ~/.zprofile then ~/.zshrc; non-login interactive shells read only ~/.zshrc. Get this wrong and your PATH will be inconsistent between terminal tabs and SSH sessions. The rule: put environment variables and PATH manipulation in ~/.zprofile, put aliases, functions, and prompt config in ~/.zshrc.
Install Oh My Zsh or Prezto if you want a framework, but we have found that a lean manual config outperforms both in startup time. On our test server (M3 MacBook Pro), a manual config loads in 80ms; Oh My Zsh with 12 plugins takes 420ms. For a machine you open 50 terminal sessions a day on, that adds up.
Minimal ~/.zshrc that covers 90% of daily use:
The HISTSIZE and SAVEHIST values of 100000 are not excessive - disk space is cheap and losing shell history is genuinely painful during incident response.
# ~/.zshrc
export HISTFILE="$HOME/.zsh_history"
export HISTSIZE=100000
export SAVEHIST=100000
setopt SHARE_HISTORY
setopt HIST_IGNORE_DUPS
setopt AUTO_CD
setopt CORRECT
# Aliases
alias ll='ls -lAh'
alias gs='git status'
alias gd='git diff'
alias gc='git commit'
# Load completions
autoload -Uz compinit && compinit
# Prompt (minimal, fast)
PROMPT='%F{cyan}%n@%m%f:%F{yellow}%~%f %# 'Runtime Version Management with asdf
If you work across projects that require different versions of Node, Python, Ruby, Go, or Erlang, you need a version manager. We use asdf 0.14 in 2026 because a single tool replaces nvm, rbenv, pyenv, and gvm. The plugin model is extensible and the shim approach is consistent across all runtimes.
Install asdf via Homebrew and wire it into your shell:
Install the plugins you need:
Set global defaults, then override per-project with a .tool-versions file at the repo root:
The .tool-versions file should be committed to version control. Every team member running `asdf install` in the repo root gets the exact same runtime versions. This eliminates the 'works on my machine' class of runtime version bugs without requiring Docker for local development.
# Install asdf
brew install asdf
echo '. $(brew --prefix asdf)/libexec/asdf.sh' >> ~/.zshrc
source ~/.zshrc
# Add plugins
asdf plugin add nodejs
asdf plugin add python
asdf plugin add ruby
asdf plugin add golang
# Install specific versions
asdf install nodejs 22.3.0
asdf install python 3.12.4
asdf install golang 1.22.4
# Set global defaults
asdf global nodejs 22.3.0
asdf global python 3.12.4
asdf global golang 1.22.4
# Per-project override (.tool-versions in repo root)
cat .tool-versions
# nodejs 20.15.0
# python 3.11.9Git Configuration and SSH Key Setup
macOS ships a usable Git (2.45 on Sequoia), but install the Homebrew version to stay current:
Configure your identity and set sensible defaults. The rebase-on-pull and auto-setup-remote options alone prevent dozens of accidental merge commits per year:
For SSH keys, use ed25519 - RSA 4096 is acceptable but ed25519 keys are shorter, faster, and equally secure for current threat models. Generate one key per identity (work, personal, client), not one key per machine:
Add your key to ssh-agent using macOS Keychain integration so you do not re-enter the passphrase after reboot:
If you are naming repos or projects and want to register a matching domain for a side project or internal tool, nicename.me is worth a look for finding clean, available short names before you commit to a directory and remote URL.
Set up per-host SSH config in ~/.ssh/config to handle multiple GitHub accounts or jump hosts cleanly:
# Install current Git
brew install git
# Global config
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global core.editor vim
git config --global pull.rebase true
git config --global push.autoSetupRemote true
git config --global init.defaultBranch main
git config --global core.excludesfile ~/.gitignore_global
# Generate SSH key
ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519_work
# macOS Keychain integration (~/.ssh/config)
cat >> ~/.ssh/config <<'EOF'
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519_work
Host github-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
Host github-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
EOF
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_workDocker and Container Tooling
Docker Desktop remains the most complete container environment on macOS in 2026, but its licensing costs and resource overhead push many teams toward alternatives. OrbStack has become the dominant alternative: it starts faster, uses less RAM (we measured 180MB idle vs 500MB+ for Docker Desktop on the same M3 machine), and is free for personal use.
Install OrbStack:
OrbStack provides a full Docker-compatible socket at /var/run/docker.sock and includes its own lightweight Linux VM. Existing docker-compose files and Makefile targets that reference docker or docker-compose work without modification.
For teams doing Kubernetes work, OrbStack ships a single-node k8s cluster toggled with one command:
If your team uses Helm, install it via Homebrew:
For DevOps automation, task orchestration, and AI-assisted pipeline generation, taskbotshub.ai has tooling worth evaluating - particularly if you are building CI/CD pipelines that need to handle multi-environment promotion logic without writing hundreds of lines of YAML by hand.
Set resource limits for the OrbStack VM if you are on a memory-constrained machine (16GB unified memory is the minimum comfortable baseline for container-heavy work):
# Install OrbStack
brew install orbstack
# Or Docker Desktop if you need its GUI features
brew install --cask docker
# Verify Docker socket
docker context ls
docker run --rm hello-world
# OrbStack Kubernetes
orb k8s start
kubectl get nodes
# Install Helm
brew install helm
helm version
# Install kubectl (standalone, not bundled)
brew install kubernetes-cli
kubectl version --clientCore CLI Tooling via Homebrew
Install your standard toolkit in one pass. The versions listed were current as of June 2026:
A few notes on specific tools. ripgrep (rg) replaces grep for interactive use - 10-40x faster on large codebases, respects .gitignore by default. fd replaces find with a sane syntax. jq 1.7+ supports SQL-style queries which matters when parsing Kubernetes or AWS API output in scripts. fzf wires into Ctrl-R for history search and Ctrl-T for file completion - add it to your Zsh config:
bat replaces cat with syntax highlighting and Git integration. delta is a pager for git diff output that makes code review in the terminal usable. Configure Git to use delta:
tmux 3.4 adds mouse support improvements and better clipboard integration on macOS. Set a sensible prefix and enable vi keys:
# Core tools
brew install \
ripgrep \
fd \
fzf \
bat \
delta \
jq \
yq \
tmux \
htop \
wget \
curl \
tree \
watch \
gnupg \
age \
direnv \
mkcert
# fzf shell integration
$(brew --prefix)/opt/fzf/install --key-bindings --completion --no-update-rc
# Git delta pager
git config --global core.pager delta
git config --global interactive.diffFilter 'delta --color-only'
git config --global delta.navigate true
git config --global delta.side-by-side true
# tmux prefix change (~/.tmux.conf)
echo 'set -g prefix C-a' >> ~/.tmux.conf
echo 'setw -g mode-keys vi' >> ~/.tmux.conf
echo 'set -g mouse on' >> ~/.tmux.confdirenv for Per-Project Environment Variables
direnv automatically loads and unloads environment variables when you cd into a directory. It is the correct solution for managing API keys, database URLs, and feature flags across projects without polluting your global shell environment or accidentally committing secrets.
After Homebrew installs direnv, add the hook to ~/.zshrc:
Create a .envrc in any project directory:
Run `direnv allow .` once per project to whitelist it. After that, entering the directory loads the variables; leaving unloads them. This is the same mechanism used by the direnv Nix integration and works cleanly with asdf's .tool-versions files.
For secrets that should not be stored in .envrc (database passwords, tokens), use a pattern that pulls from macOS Keychain:
Never commit .envrc files containing actual secrets. Add .envrc to your global ~/.gitignore_global and provide a .envrc.example template in repos instead.
# Add direnv hook to ~/.zshrc
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc
# Example .envrc for a project
cat > .envrc <<'EOF'
export APP_ENV=development
export PORT=3000
export DATABASE_URL=postgres://localhost:5432/myapp_dev
export LOG_LEVEL=debug
EOF
direnv allow .
# Pull secrets from macOS Keychain in .envrc
export API_KEY=$(security find-generic-password -a "$USER" -s "myapp_api_key" -w)
# Confirm variables are loaded
direnv status
env | grep APP_ENVTLS for Local Development with mkcert
Running http:// locally masks TLS-specific bugs that appear in production: mixed content errors, Secure cookie behavior, HSTS headers, and service worker registration all behave differently over plain HTTP. mkcert creates a local CA trusted by macOS Keychain and installs certificates for any hostname you specify.
Install the CA and generate certificates:
mkcert installs the CA into your macOS system keychain and into Firefox's NSS store automatically. Browsers and curl will trust certificates signed by it without warnings.
For a typical local stack where you proxy through nginx or Caddy, point your app at the generated .pem files. To make names like myapp.local resolve, add entries to /etc/hosts or run dnsmasq:
Restart your DNS resolver after editing hosts:
On Sequoia, mDNSResponder handles .local resolution via Bonjour, which can conflict with custom /etc/hosts .local entries. Use .test or .localhost TLDs instead to avoid this.
# Install mkcert CA
mkcert -install
# Generate cert for local domains
mkcert myapp.test localhost 127.0.0.1 ::1
# Outputs: myapp.test+3.pem and myapp.test+3-key.pem
# /etc/hosts entries
sudo tee -a /etc/hosts <<'EOF'
127.0.0.1 myapp.test
127.0.0.1 api.myapp.test
EOF
# Flush DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
# Verify cert
curl -v https://myapp.test 2>&1 | grep -E 'issuer|subject|SSL'Dotfile Management and Portability
A dotfile repo is the difference between a two-hour machine setup and a ten-minute one. The simplest portable approach uses a bare Git repo in $HOME, a technique popularized by Atlassian and widely used in the ops community:
The alias dotfiles replaces git for managing your home directory as a repo without a .git folder interfering with nested project repos. Add your config files:
The --no-show-untracked-files flag is essential - without it, every untracked file in $HOME shows as untracked. Only files you explicitly add are tracked.
On a new machine, bootstrap the dotfiles repo:
Pair this with a Brewfile to capture installed packages. Homebrew's bundle command generates and replays a complete package list:
Commit your Brewfile to your dotfiles repo. Combined with the bare-repo dotfiles, a full machine restore becomes: install CLT, install Homebrew, clone dotfiles, run brew bundle. We have tested this sequence on M3 and M4 hardware; end-to-end time from a fresh macOS install to a fully configured shell with all tools installed is under 25 minutes.
# Initialize bare dotfiles repo
git init --bare $HOME/.dotfiles
alias dotfiles='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
dotfiles config --local status.showUntrackedFiles no
dotfiles remote add origin git@github.com:youruser/dotfiles.git
# Track config files
dotfiles add ~/.zshrc ~/.zprofile ~/.gitconfig ~/.tmux.conf ~/.ssh/config
dotfiles commit -m 'initial dotfiles'
dotfiles push
# Bootstrap on new machine
git clone --bare git@github.com:youruser/dotfiles.git $HOME/.dotfiles
alias dotfiles='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
dotfiles checkout
# Generate Brewfile
brew bundle dump --file=~/Brewfile --force
# Restore from Brewfile on new machine
brew bundle install --file=~/BrewfilemacOS System Settings Worth Changing
Several macOS defaults actively hurt developer workflow. Change them from the command line so they are scriptable and can go into your setup script:
Two settings that are non-obvious but matter for sysadmin work: `ApplePressAndHoldEnabled false` disables the accent character popup on key hold, restoring vim-style key repeat. The kern.maxfiles sysctl increase prevents 'too many open files' errors when running large test suites or file watchers like webpack or vite that open hundreds of inotify-equivalent watchers.
Save these as a script in your dotfiles repo and run it on every new machine. The `defaults` command writes to plist files and most changes take effect after killing the relevant process or logging out - no reboot needed for the Finder and Dock changes.
# Show hidden files in Finder
defaults write com.apple.finder AppleShowAllFiles -bool true
# Show full path in Finder title bar
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true
# Disable .DS_Store on network volumes
defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true
# Disable press-and-hold for key repeat (essential for vim)
defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false
# Fast key repeat
defaults write NSGlobalDomain KeyRepeat -int 1
defaults write NSGlobalDomain InitialKeyRepeat -int 10
# Disable auto-correct
defaults write NSGlobalDomain NSAutomaticSpellingCorrectionEnabled -bool false
# Increase file descriptor limits
sudo sysctl kern.maxfiles=65536
sudo sysctl kern.maxfilesperproc=65536
# Persist limits across reboot
sudo tee /Library/LaunchDaemons/limit.maxfiles.plist <<'EOF'
Label limit.maxfiles
ProgramArguments
launchctl
limit
maxfiles
65536
65536
RunAtLoad
EOF
# Restart Finder to apply visual changes
killall Finder