macos-configuration/README.md

macOS Configuration

Personal macOS setup. This README is a complete, ordered runbook for setting up a fresh machine — follow it top to bottom and you end up with a working environment.

Two kinds of files live here:

• Symlinked — the file in this repo is the live config (fish, starship, ssh, kube, npm, NuGet). Edit either side, they're the same file.
• Copied — files that can't be symlinked (/etc/hosts, Claude/Serena settings, the brewfile). Refresh them from the machine with ./update.fish.

Fresh machine setup — the fast way

Get this repo onto the machine (USB stick copy or a clone) and run:

/bin/bash setup.sh

The script is idempotent and does steps 1–9 below automatically: it copies the repo to ~/Repositories/personal/macos-configuration (so it works straight off a USB stick), installs Command Line Tools and Homebrew, runs the brew bundle, creates all symlinks, restores the copied configs, sets fish as the default shell, and installs the .NET SDK. At the end it prints the manual steps that remain (1Password/SSH keys, iTerm2 profile import, gh auth login + repo cloning, WireGuard, app sign-ins).

The sections below document what the script does, for reference or manual runs.

Fresh machine setup — step by step

1. Install Command Line Tools and clone this repo

xcode-select --install
mkdir -p ~/Repositories/personal
git clone https://github.com/awatertrevi/macos-configuration.git ~/Repositories/personal/macos-configuration
cd ~/Repositories/personal/macos-configuration

(First clone happens over HTTPS; once 1Password + SSH are set up below, remotes work over SSH.)

2. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"

3. Install all packages, casks, and VS Code extensions

brew bundle --file=brewfile

This installs everything: CLI tools (fish, gh, node, pnpm, uv, opentofu, …), apps (1Password, iTerm2, Docker Desktop, Fork, VS Code, …), fonts, and VS Code extensions.

4. Sign in to 1Password and enable the SSH agent

Open 1Password → Settings → Developer → enable SSH Agent. The ssh-config symlinked below routes all SSH auth through the 1Password agent (~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock), so the private keys never live on disk — only the .pub files referenced in ssh-config need to exist in ~/.ssh/ (1Password can export them, or copy them from the old machine).

5. Symlink configuration files

Run from the repo root:

mkdir -p ~/.config/fish ~/.kube ~/.nuget/NuGet
ln -sf $(pwd)/fish-config.fish ~/.config/fish/config.fish
ln -sf $(pwd)/starship.toml    ~/.config/starship.toml
ln -sf $(pwd)/ssh-config       ~/.ssh/config
ln -sf $(pwd)/kube-config      ~/.kube/config
ln -sf $(pwd)/.npmrc           ~/.npmrc
ln -sf $(pwd)/NuGet.Config     ~/.nuget/NuGet/NuGet.Config

6. Restore the copied configs

mkdir -p ~/.claude ~/.serena
cp claude-settings.json ~/.claude/settings.json
cp serena_config.yml    ~/.serena/serena_config.yml
sudo cp hosts /etc/hosts

7. Set fish as the default shell

echo /opt/homebrew/bin/fish | sudo tee -a /etc/shells
chsh -s /opt/homebrew/bin/fish

8. Configure iTerm2

iTerm2 → Settings → Profiles → Other Actions → Import JSON Profiles → select iterm-profile.json, then set it as the default profile. (Requires the Fira Code Nerd Font installed in step 3.)

9. Install the .NET 10 SDK

fish install-dotnet10.fish

Installs into ~/.dotnet via the official dotnet-install script and prints the fish_add_path line to persist it if needed.

10. Clone work repositories

gh auth login   # authenticate the GitHub CLI first
fish clone-resoftware-repos.fish

Clones every repo in the resoftware GitHub org via SSH into ~/Repositories/{customer-number}/{repo-name}, based on each repo's customer-number custom property. Safe to re-run — existing clones are skipped.

11. WireGuard tunnel to home network (optional)

meerkoet-proxy.conf is a WireGuard client config for the home (Fritz!Box) network. Import it into the WireGuard app (installable from the App Store) via Import Tunnel(s) from File.

12. Manual leftovers

Things not automated here:

• Sign in: iCloud, Chrome/Zen, Slack, Spark, Google Drive, Docker Desktop, Todoist.
• JetBrains Toolbox → sign in and install the IDEs you use.
• Grant permissions as apps ask (Bartender, BetterTouchTool, CleanShot, Mos, Cursr).
• Alfred / BetterTouchTool: restore licenses and sync/import preferences.

Keeping this repo up to date

The symlinked files are always current by construction. Refresh the copied ones with:

./update.fish

It re-dumps the brewfile (brew bundle dump --force) and re-copies ~/.claude/settings.json, ~/.serena/serena_config.yml, and /etc/hosts into the repo. Review git diff afterwards and commit.