Dev Machine — Laptop Setup Guide

Reproducible developer-laptop setup. Homebrew baseline, shell + editor + terminal, language toolchains (Python/Go/Node/Rust), cloud + K8s tools, AI tooling, Git hygiene. Bootstrap recipe + dotfiles strategy so a fresh laptop reaches parity in under two hours.

The laptop is half the homelab. Every command in /root starts at a terminal prompt on this machine. The dev setup deserves the same reproducibility discipline as the server. Goal: a fresh laptop reaches productive parity in under 2 hours, via one Brewfile + one dotfiles repo + one bootstrap script.

What this guide is

This guide is the reproducible setup recipe for the dev laptop /root runs on. It covers:

1. Hardware — what laptop fits the program, when to upgrade.
2. The base layer — Homebrew + xcode-select on macOS; apt + a sensible baseline on Linux.
3. Shell + terminal + editor — the three surfaces you’ll spend 90% of your /root hours in.
4. Language toolchains — Python (uv / pyenv), Go, Node, Rust. Per-year needs.
5. Cloud + K8s + IaC tools — kubectl, helm, flux, terraform, cloud CLIs.
6. AI tooling — Claude Code, the editor extensions, local LLMs.
7. Git hygiene — signed commits, pre-commit, secret scanning.
8. Productivity layer — Raycast, window managers, clipboard managers.
9. The Brewfile + dotfiles + bootstrap script — the reproducibility artifacts.
10. Troubleshooting — the failures you’ll see when bootstrapping a new laptop.

The guide assumes macOS on Apple Silicon as the primary path (the natural choice given Apple-platform engineering work) and flags Linux alternatives where they differ. Windows + WSL2 is workable but adds friction the guide doesn’t cover.

1. Hardware — what laptop

Three sane choices for the /root laptop:

Minimum spec for /root: 16GB RAM, 512GB SSD. Y1-Y2 fit easily; Y3 starts to feel tight when running multiple Docker containers + a Postgres + a heavyweight IDE; consider 32GB if buying new.

The laptop is the workstation, not the server. Compute-heavy work runs on the server or in the cloud. The laptop’s job is: terminal, editor, browser, the occasional local Docker, video calls. Don’t size for “could I run Kubernetes locally” — the homelab server handles that.

2. Base layer — package manager + dev fundamentals

macOS (the primary path)

# 1. Install Xcode Command Line Tools (required by Homebrew, Git, most compilers).
xcode-select --install

# 2. Install Homebrew (the macOS package manager).
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3. Add Homebrew to PATH (Apple Silicon installs to /opt/homebrew).
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 4. Confirm.
brew --version    # 4.x as of mid-2026

Linux (Ubuntu / Debian)

sudo apt update
sudo apt install -y build-essential curl git zsh

# Install Homebrew on Linux (yes, Linuxbrew works) — gives you Brewfile parity with macOS.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to PATH:
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Note: Linuxbrew duplicates apt-installed packages in a separate prefix. That’s fine; it keeps the Brewfile portable.

3. Shell + terminal + editor

Shell: zsh + starship prompt

macOS defaults to zsh; Linux often defaults to bash. Either way, zsh is /root’s shell.

brew install starship    # the prompt
brew install zsh-autosuggestions zsh-syntax-highlighting

# Add to ~/.zshrc:
eval "$(starship init zsh)"
source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source $(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

# Optional: Oh My Zsh adds aliases/plugins. Use it if it suits you, skip if you prefer minimal.
# /root doesn't depend on OMZ. Starship + a small ~/.zshrc is enough.

Starship config (~/.config/starship.toml): start minimal — show user, host, dir, git branch, kubectl context. Add language/version indicators only if you find yourself wanting them. The /root philosophy on prompts: signal over noise.

Terminal: pick one and commit

brew install --cask iterm2 for the default. Config-tune later: fonts (a Nerd Font like JetBrainsMono Nerd Font), color scheme, key bindings (Cmd-T new tab, Cmd-D split, Cmd-Arrow navigation).

Editor: pick one and commit

Two reasonable paths:

Path A: VSCode (recommended for /root)

brew install --cask visual-studio-code

# Settings sync via GitHub account = reproducibility for free.

Extensions worth installing on day one (install via the Extensions sidebar or code --install-extension):

ms-python.python                  Python core
ms-python.vscode-pylance          Python LSP
golang.Go                         Go tooling
rust-lang.rust-analyzer           Rust LSP
hashicorp.terraform               Terraform
hashicorp.HCL                     HCL syntax
redhat.vscode-yaml                YAML (K8s manifests)
ms-azuretools.vscode-docker       Docker
ms-kubernetes-tools.vscode-kubernetes-tools   K8s
weaveworks.vscode-gitops-tools    Flux (later)
yzhang.markdown-all-in-one        Markdown
streetsidesoftware.code-spell-checker         Spell check
eamodio.gitlens                   Git inline
github.copilot                    (optional, paid; Claude Code is the /root preference)
anthropic.claude-code             Claude Code extension

Path B: Neovim (recommended if you want to learn Vim properly)

brew install neovim ripgrep fd lazygit
# Choose a distro: LazyVim or AstroNvim are both excellent.

git clone https://github.com/LazyVim/starter ~/.config/nvim
rm -rf ~/.config/nvim/.git
nvim    # let Lazy bootstrap. ~30 seconds first run.

Neovim has a steeper curve (3-4 weeks to fluency) but pays dividends over a 5-year program. /root doesn’t take a side; pick the one you’ll actually use.

4. Language toolchains

The program touches Python, Go, Node, Rust. Install with version managers so each project can pin a version.

Python (heaviest use Y4-Y5)

# uv: Astral's fast Python project manager. /root recommendation.
brew install uv

# Verify and create a sample project:
uv --version
mkdir test-py && cd test-py
uv init
uv add requests
uv run python -c "import requests; print(requests.__version__)"

uv replaces pip + virtualenv + pyenv + poetry with one fast tool. Per-project Python version pinning via pyproject.toml. Faster than alternatives by 10-100×.

If you prefer the traditional path: brew install pyenv + pyenv install 3.12.x.

Go (used Y1 Phase 4 onward; the language of pulse, platform-ctl, llm-gateway)

brew install go
# /root pins Go versions per-project via go.mod's `go 1.22` directive.
# For multi-version support: brew install asdf, then `asdf plugin add golang`, `asdf install golang 1.22.5`.

go version    # confirm 1.22+

Node (light use — mostly tooling, Y5 Studio frontend)

brew install fnm    # fast node manager (alternative to nvm)
fnm install 22
fnm default 22
node --version

Or volta if you prefer that.

Rust (light use — optional, for OS-internals curiosity in Y3)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Adds rustup, cargo, rustc.
. "$HOME/.cargo/env"
rustc --version

5. Cloud + K8s + IaC tools

The /root core CLI bundle. Install all via Homebrew.

# Kubernetes & GitOps:
brew install kubectl kubectx        # kubectx + kubens for context/namespace switching
brew install derailed/k9s/k9s       # TUI for K8s — your main K8s navigator
brew install helm
brew install fluxcd/tap/flux

# Local K8s for development (optional; basecamp is on the homelab):
brew install kind                    # K8s in Docker — for quick experiments

# IaC:
brew install opentofu                # the OSS Terraform fork (recommended OSS path)
brew install terraform               # original Terraform; install if a project requires it
brew install hashicorp/tap/packer    # if you'll build images

# Cloud CLIs:
brew install awscli
brew install --cask google-cloud-sdk
# brew install azure-cli            # only if you'll touch Azure

# Secrets:
brew install hashicorp/tap/vault     # OSS Vault CLI
brew install sops                    # Mozilla sops — works with age, KMS, etc.
brew install age                     # modern symmetric/asymmetric encryption

# GitHub:
brew install gh

# Containers (covered in the next section).

Docker / container runtime — careful about Docker Desktop licensing

Docker Desktop is free for personal use but requires a paid license for commercial use (companies > 250 employees or > $10M revenue). Apple, Google, most large employers — Docker Desktop is NOT free for you when used for work. The /root recommendation for the dev machine:

/root’s recommendation: colima for purity, OrbStack for ergonomics if your employer permits. Avoid Docker Desktop unless your org has a license.

# colima path:
brew install colima docker docker-compose
colima start --cpu 4 --memory 8 --disk 60
docker run hello-world

6. AI tooling — the /root assistant stack

Claude Code (the /root reference)

# Install Claude Code CLI (the canonical Anthropic agentic dev tool):
npm install -g @anthropic-ai/claude-code     # or via Homebrew when available
claude --version

# Authenticate (uses your Claude.ai or API account):
claude login

Optional but useful: install the Claude Code extension in your editor (VSCode, JetBrains, Neovim plugin) for in-editor agentic coding.

Local LLM (for offline + privacy + Y5 prep)

brew install ollama
ollama serve &
ollama pull qwen2.5:7b    # ~4GB; runs comfortably on 16GB+ Apple Silicon
ollama run qwen2.5:7b "Explain control-loops in three sentences."

Ollama is vLLM’s consumer-friendly cousin — runs llama.cpp underneath; works on Apple Silicon via Metal; CUDA on Linux. /root uses it for offline experimentation and local prompt iteration before paying upstream APIs.

Cursor / Zed / Continue (alternatives if you don’t want VSCode)

• Cursor: a VSCode fork with first-class AI. Paid subscription. Excellent product; some shops disallow it for data-handling reasons.
• Zed: native, fast, OSS, has AI integrations. Earlier in maturity.
• Continue: VSCode/JetBrains extension that brings agentic AI to existing editor.

The /root posture is VSCode + Claude Code extension for the default; switch to Cursor only if you have a strong product preference.

Optional: API keys

You’ll need keys by Y5. Set them up earlier so you can experiment safely:

# Add to ~/.zshrc (or better: load from a private file outside dotfiles):
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

Never commit API keys to Git. Use gitleaks (below) to scan before push.

7. Git hygiene

brew install git gh gitleaks pre-commit

# Configure Git:
git config --global user.name  "John Carl Abucay"
git config --global user.email "<your-personal-email>"
git config --global init.defaultBranch main
git config --global pull.rebase true        # rebase on pull, cleaner history
git config --global core.editor "code --wait"     # or `nvim` if Neovim

# Sign commits with SSH key (modern; simpler than GPG):
git config --global gpg.format ssh
git config --global commit.gpgsign true
git config --global user.signingkey "/Users/$USER/.ssh/id_ed25519.pub"

# Generate SSH key if you don't have one:
ssh-keygen -t ed25519 -C "<your-email>"
gh auth login           # adds the SSH key to GitHub
gh ssh-key add ~/.ssh/id_ed25519.pub --type signing

Pre-commit hooks (run gitleaks before every commit)

In every /root repo:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

Then:

pre-commit install

Every git commit now scans for secrets first. This single hook prevents the single biggest career-impacting mistake (committing a secret).

8. Solo PR workflow

The Abukix workspace is operated by one engineer. There’s no team to review your PRs; there’s only past-you (overnight), AI as a sanity check, and external readers at consequential moments. The workflow that makes this work — encoded in ADR-0001 — is the rhythm below.

The five-step rhythm

1. Branch.       Locally, off main:
                   git checkout -b feat/add-llm-gateway-caching
                 No work on main directly. Ever.

2. Open a PR.    Push the branch; open a PR against main.
                 GitHub renders the PR template (.github/pull_request_template.md).
                 Fill it: summary, why, validation, risk, public-safety.

3. CI runs.      The .github/workflows/ci-check.yml workflow fires automatically.
                 Required checks per the repo's branch-protection rules:
                   - yaml-lint           (every repo)
                   - gitleaks            (every repo)
                   - kustomize-build     (basecamp)
                   - flux-validate       (basecamp)
                   - kyverno-test        (basecamp)
                   - go-test             (Go repos)
                   - python-test         (Python repos)
                 If anything red, fix locally, push again, CI re-runs.

4. Sleep on it.  When CI is green, DO NOT MERGE. Walk away.
                 Re-read the PR tomorrow morning with fresh eyes.
                 This is the cheapest "second pair of eyes" you have —
                 past-you reviewing today-you's decision.

5. Merge.        Tomorrow, if the PR still makes sense:
                   - For LOW-risk: self-merge.
                   - For MEDIUM-risk: `/root-tutor` skim of the diff first.
                   - For HIGH-risk: Claude Code PR-review mode + external
                     human reviewer (if available).
                   - For CRITICAL or public-flipping: `/pre-publish-check`
                     skill MUST run; external reviewer required if Y5
                     (the Pattern Paper rule applies to anything labeled
                     a public capstone artifact).
                 Squash-merge to keep history linear.

Risk classification — when to require external review

When to break the rhythm (honestly)

✓ Acceptable bypasses:
  - Typo / one-character fixes on the curriculum site. Commit to main directly.
  - Weekly log entries. They land in ops-handbook (private); PR ceremony unnecessary.
  - Local-only experimental branches that never get merged.

✗ NOT acceptable bypasses:
  - "I'm tired, just merge it" on basecamp.
  - "It's late, the overnight wait will slow me down."
  - Public flips (basecamp going public, Studio launch, blog post publish)
    without the public-safety check.
  - Any HIGH/CRITICAL change without sleeping on it.

The rhythm exists because tired-you and excited-you both ship bad code. Past-you-overnight catches it cheaply.

Bootstrap recipe for a new Abukix repo

Every new repo needs the git-templates installed. The files live in meta/git-templates/:

cd <new-abukix-repo>
mkdir -p .github/workflows

# Copy the templates:
ROOT=~/abukix-root/root/src/content/docs/meta/git-templates
cp $ROOT/CODEOWNERS                .github/CODEOWNERS
cp $ROOT/pull-request-template.md  .github/pull_request_template.md
cp $ROOT/ci-check.yml              .github/workflows/ci-check.yml

# Replace placeholders:
sed -i '' 's|@<your-handle>|@<your-actual-github-handle>|g' .github/CODEOWNERS

# Configure branch protection (one-time per repo):
# See meta/git-templates/branch-protection-rules.md for the gh api recipe.

git add .github CODEOWNERS
git commit -m "ci: bootstrap repo via Abukix git-templates"
git push

After committing, configure the branch protection rules per meta/git-templates/branch-protection-rules.

Cross-references

• ADR-0001 — the decision this workflow encodes
• meta/git-templates/ — the file templates this workflow uses
• pre-publish-check skill — the safety guard run on public-flip PRs
• root-tutor skill — the senior-engineer instructor invoked on MEDIUM-risk PRs

9. Productivity layer (macOS)

Optional but recommended once /root settles in:

brew install --cask raycast              # Spotlight replacement; the macOS launcher /root uses
brew install --cask rectangle             # window management (free; alternative: Magnet, paid)
brew install --cask karabiner-elements    # keyboard remapping (Caps Lock → Esc/Ctrl)
brew install --cask alfred                # alternative to Raycast (paid power-user features)

# Notes (pick one):
brew install --cask obsidian              # the /root recommended notes app; Markdown vault on Git
brew install --cask logseq                # alternative: outliner-first
brew install --cask notion                # cloud-hosted; not OSS

# Browsers:
brew install --cask arc                    # tab-rich power browser
brew install --cask firefox                # backup; the OSS path
# Brave, Edge, etc. as you wish

# Other useful:
brew install --cask 1password              # if you use 1Password (alternative: open-source `pass` or Bitwarden)
brew install --cask bitwarden              # OSS password manager (recommended for /root)
brew install --cask spotify                # because Sunday weekly log music matters

Raycast: the launcher worth investing in

Raycast replaces Spotlight + Alfred. The /root extensions worth installing on day one:

• Calculator (Math)
• Brew (manage Homebrew from Raycast)
• GitHub (PRs, issues without leaving keyboard)
• Kubernetes (kubectx, kubens, k9s shortcuts)
• 1Password / Bitwarden integration
• Snippets (text expansion)
• Quicklinks (bookmark + parameterize URLs)

9. The reproducibility artifacts

This is the part that makes “fresh laptop in 2 hours” real. Three artifacts:

Artifact 1: Brewfile

# ~/.config/Brewfile  (or wherever your dotfiles live)

# Taps
tap "fluxcd/tap"
tap "hashicorp/tap"
tap "derailed/k9s"

# CLI tools — base
brew "git"
brew "gh"
brew "zsh"
brew "starship"
brew "zsh-autosuggestions"
brew "zsh-syntax-highlighting"

# CLI tools — language
brew "uv"
brew "go"
brew "fnm"

# CLI tools — K8s + cloud + IaC
brew "kubectl"
brew "kubectx"
brew "helm"
brew "fluxcd/tap/flux"
brew "kind"
brew "opentofu"
brew "awscli"
brew "hashicorp/tap/vault"
brew "sops"
brew "age"
brew "derailed/k9s/k9s"

# CLI tools — Git hygiene
brew "gitleaks"
brew "pre-commit"

# CLI tools — container runtime (pick one)
brew "colima"
brew "docker"
brew "docker-compose"

# CLI tools — utilities
brew "ripgrep"
brew "fd"
brew "fzf"
brew "bat"        # `cat` with syntax highlighting
brew "eza"        # modern `ls`
brew "jq"
brew "yq"
brew "lazygit"
brew "neovim"
brew "tmux"
brew "tree"
brew "htop"
brew "watch"

# GUI apps
cask "iterm2"
cask "visual-studio-code"
cask "raycast"
cask "rectangle"
cask "karabiner-elements"
cask "obsidian"
cask "bitwarden"
cask "arc"
cask "firefox"
cask "google-cloud-sdk"

# Mac App Store apps (requires `brew install mas` first):
# mas "Xcode", id: 497799835

Run it: brew bundle --file=~/.config/Brewfile.

On a new machine: clone your dotfiles, cd to where Brewfile lives, run brew bundle. 30-45 minutes later, every CLI + GUI tool is installed.

Artifact 2: dotfiles repo

github.com/<you>/dotfiles — a Git repo holding:

dotfiles/
├── .zshrc                       symlink target
├── .zprofile
├── .gitconfig
├── .gitignore_global
├── .config/
│   ├── starship.toml
│   ├── nvim/                     (if Neovim user)
│   ├── Brewfile                 (above)
│   └── ...
├── bin/                         personal scripts
└── install.sh                   bootstrap script (see Artifact 3)

Symlink strategy: stow is the standard tool.

brew install stow
cd ~/dotfiles
stow .          # symlinks .zshrc etc. into $HOME

stow lets you organize dotfiles as subdirs (e.g., dotfiles/zsh/.zshrc, dotfiles/git/.gitconfig) and selectively stow zsh or stow git. For /root, flat is fine.

Artifact 3: bootstrap script

#!/usr/bin/env bash
# ~/dotfiles/install.sh — run on a fresh laptop after installing Xcode tools + Homebrew.
set -euo pipefail

# 1. Clone dotfiles.
if [[ ! -d ~/dotfiles ]]; then
  git clone https://github.com/<you>/dotfiles.git ~/dotfiles
fi
cd ~/dotfiles

# 2. Stow.
stow .

# 3. Brewfile.
brew bundle --file=~/dotfiles/.config/Brewfile

# 4. Set zsh as default shell.
if [[ "$SHELL" != *zsh* ]]; then
  chsh -s "$(which zsh)"
fi

# 5. Generate SSH key if missing.
if [[ ! -f ~/.ssh/id_ed25519 ]]; then
  ssh-keygen -t ed25519 -C "<your-email>" -N "" -f ~/.ssh/id_ed25519
  echo "Add this public key to GitHub:"
  cat ~/.ssh/id_ed25519.pub
fi

# 6. Authenticate gh CLI.
gh auth status &>/dev/null || gh auth login

# 7. (Optional) Trigger uv-managed Python toolchain install.
uv python install 3.12

echo "Bootstrap complete. Open a new terminal."

Run on the new laptop: bash ~/dotfiles/install.sh. Target: under 2 hours from xcode-select --install to a working /root-ready laptop.

10. Troubleshooting — the failures you’ll see on a fresh laptop

Homebrew install fails with “shallow clone” warnings

Cause: corporate network proxying GitHub.

Fix: if on a personal network, retry. If on a corporate network, configure Homebrew’s proxy:

export HTTPS_PROXY=http://<corp-proxy>:8080
brew install ...

brew bundle fails on a cask install with Gatekeeper

Symptom: cask install <foo> fails; macOS reports “developer cannot be verified.”

Fix: open System Settings → Privacy & Security → scroll to the bottom → “Open Anyway” for the most recent blocked app. Re-run brew bundle.

Apple Silicon: x86 binary won’t run

Symptom: running a downloaded binary returns “bad CPU type in executable.”

Fix: install Rosetta 2 (the macOS x86 translation layer):

softwareupdate --install-rosetta --agree-to-license

Most Homebrew packages have Apple Silicon (arm64) builds, so you rarely need Rosetta. The --cask GUI apps are universal. Specific tooling (older vendor CLIs) sometimes needs Rosetta.

Python version conflicts after uv install

Symptom: python resolves to a system version, not uv’s; project’s pyproject.toml Python version ignored.

Fix: uv manages Python per project. Inside a project: uv run python uses the pinned version. Don’t use the system python; if you need a global Python:

uv python install 3.12
uv tool install ruff      # global tools via uv tool

Docker Desktop license warning at work

Symptom: Docker Desktop shows a license warning; IT raises a flag.

Fix: uninstall Docker Desktop. Use colima or Podman Desktop instead. Both are OSS-licensed and free for commercial use.

brew uninstall --cask docker
brew install colima
colima start

Git: commits not signed despite config

Symptom: git log --show-signature shows commits as unsigned.

Cause: signing key path wrong, or allowedSignersFile not set for verification.

Fix:

git config --global user.signingkey "/Users/$USER/.ssh/id_ed25519.pub"
git config --global commit.gpgsign true
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

# Create the allowed_signers file:
echo "<your-email> namespaces=\"git\" $(cat ~/.ssh/id_ed25519.pub)" >> ~/.ssh/allowed_signers

Raycast and clipboard manager conflict

Symptom: Raycast clipboard history doesn’t capture; another clipboard manager (Maccy, Paste) intercepting.

Fix: pick one. Two clipboard managers fight each other. /root uses Raycast’s built-in clipboard history; uninstall the other.

VSCode settings sync not picking up extensions

Fix: Cmd-Shift-P → “Settings Sync: Turn On” → sign in with GitHub → choose what to sync. Wait 1-2 minutes after sign-in for the first pull.

11. Update cadence

Weekly:   brew update && brew upgrade           (Sunday before the weekly log)
Monthly:  brew bundle dump --file=Brewfile      (refresh the Brewfile from current state)
          gh extension upgrade --all
Quarterly: review dotfiles for cruft; archive what you no longer use
Annually:  audit installed packages; remove dead ones

When you change something on the laptop that you’d want on a future laptop (a new alias, a new extension, a new tool), commit it to the dotfiles repo that day. The reproducibility artifact only works if it stays in sync with reality.

Cross-references

• Homelab Hardware — the server side
• Master Plan — the cumulative tool budget
• AI Learning Protocol — how to use Claude Code without becoming a copy-paste autopilot
• The Story — the rhythm — the day/week/month cadence the laptop supports