Skip to content

Latest commit

Β 

History

28 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

macOS Setup β€” Homebrew Edition

A centralized, reproducible macOS environment managed entirely through Homebrew β€” one package manager to rule them all.


Contents


Quick Start

1. Install Homebrew

Homebrew is the backbone of this setup. Install it first before running anything else.

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

Apple Silicon users: After installation, follow the instructions in the terminal to add Homebrew to your PATH.

2. Run the interactive installer

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Black0S/My-MacOS-Setup/main/install.sh)"

The script is a three-page flow, driven by gum.

  1. Pick a category β€” ↑↓ to move, ENTER to choose, ESC to quit.
  2. Pick packages β€” type to search, ENTER takes the highlighted row, TAB ticks several, ctrl+a takes all. Each row shows whether it is already installed. The last row goes back to the categories.
  3. Choose the operation β€” Install, Reinstall, Uninstall, or Open official page. Only the ones that make sense for your selection are offered, and all of them act on the same selection from the same page.

Homebrew output streams live in a fixed-height window while it works. Nothing is written to disk.

Useful flags: --list prints the catalogue, --dry-run previews without changing anything, --quiet swaps live output for spinners, and --all with --category NAME (plus --uninstall / --reinstall) runs non-interactively. --help has the rest.


How to Read the Catalogue

Every row lists the exact argument you pass to Homebrew.

Marker Meaning Example
token In homebrew/cask or homebrew/core β€” install directly brew install --cask ghostty
owner/tap/token Lives in a third-party tap β€” the full path works as-is brew install --cask productdevbook/tap/portkiller
– manual No Homebrew package β€” download from the project's releases page β€”

GUI apps are casks (brew install --cask …); command-line tools are formulae (brew install …).


🌐 Browsers

App Homebrew Description
Zen Browser zen Privacy-focused Firefox-based browser
Firefox firefox Mozilla's open-source browser
Google Chrome google-chrome Google's browser
Helium helium-browser Private, fast and honest Chromium browser β€” no telemetry, no ads
Orion orion WebKit browser with Firefox & Chrome extension support
Min min Minimalist, distraction-free browser
Tor Browser tor-browser Anonymous browsing via the Tor network

⚠️ Helium's cask is helium-browser. The plain helium cask is an unrelated app (Helium Desktop by koush).


πŸ–₯ Terminals

App Homebrew Description
Ghostty ghostty Fast, feature-rich terminal with platform-native UI and GPU acceleration

πŸ“ Editors

App Homebrew Description
Visual Studio Code visual-studio-code Extensible code editor by Microsoft
Cate cate Infinite zoomable canvas with editor, terminal and browser panels
CotEditor coteditor Lightweight native plain-text editor for macOS

πŸ›  Developer Tools

App Homebrew Description
TablePro tablepro Free, open-source native database client for many engines
DBX dbx 20 MB cross-platform client for 90+ databases, with built-in AI and MCP server
GitComet gitcomet Fast open-source GUI for Git workflows
CaskHub caskhub Native GUI for browsing and managing Homebrew casks
Port Killer productdevbook/tap/portkiller Monitor ports, manage k8s port-forwards, kill processes in one click
Dockev – manual Modern GUI for Docker β€” manage containers without the CLI

🐳 Containers

App Homebrew Description
OrbStack orbstack Lightweight Docker & Linux VM manager
Docker Desktop docker-desktop Official Docker Desktop for Mac
Podman Desktop podman-desktop Browse, manage and inspect containers and images
Colima colima Docker-compatible runtime β€” the GUI-free alternative to Docker Desktop (pulls in Lima itself)
container container Apple's own CLI for Linux containers in lightweight VMs on Apple silicon
Podman podman Daemonless CLI for managing OCI containers and pods
Socktainer socktainer Docker-compatible REST API on top of Apple's container
Docker CLI docker The docker command itself β€” needs a runtime such as Colima, OrbStack or Docker Desktop
Docker Compose docker-compose The docker compose plugin β€” define and run multi-container environments

ℹ️ docker and docker-compose are separate formulae β€” docker alone has no compose subcommand. After installing docker-compose, point Docker at Homebrew's plugin directory or docker compose won't be found. Add this to ~/.docker/config.json:

{ "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"] }

Colima and container are self-contained β€” brew install colima pulls in Lima as a dependency, so there's no need to install it separately.

With colima start running, docker and docker compose work unchanged against it β€” no GUI app needed anywhere.

Apple's container and podman each speak their own CLI rather than the Docker socket, so on their own they do not back the docker command. Socktainer closes that gap for container: it serves a Docker-compatible REST API, so pointing DOCKER_HOST at it makes docker and docker compose work against Apple's runtime.

brew services start socktainer
export DOCKER_HOST=unix://$HOMEBREW_PREFIX/var/run/socktainer/.socktainer/container.sock

⚠️ Socktainer pins the Apple container version it was built against. socktainer 1.2.1 requires container 1.2.0 and refuses to start against 1.3.0; upstream warns that bypassing the check with --no-check-compatibility causes XPC errors. If the service fails, read $(brew --prefix)/var/log/socktainer.log β€” it names the exact version mismatch.

The socket path depends on how socktainer is launched: under brew services it binds $HOMEBREW_PREFIX/var/run/socktainer/.socktainer/container.sock (the path in Homebrew's caveat); run by hand it binds .socktainer/container.sock relative to the current directory. lsof -p $(pgrep -f socktainer) shows which one is live.

Do not run brew services start container β€” the Apple runtime registers its own launchd agents through container system start, and the Homebrew service collides with them (Bootstrap failed: 5).

Docker Desktop's cask already installs its own docker and docker-compose binaries, so these formulae are redundant β€” and a second copy on PATH can shadow it. OrbStack ships orb/orbctl and provides the docker CLI from its own bin directory rather than through Homebrew.


πŸ’» Virtualisation

App Homebrew Description
UTM utm Full-featured virtual machines, built on QEMU

🎬 Video

App Homebrew Description
IINA iina The modern open-source video player for macOS
HandBrake handbrake-app Open-source video transcoder
Shutter Encoder shutter-encoder Professional FFmpeg-based video, audio and image converter

ℹ️ The HandBrake cask was renamed from handbrake to handbrake-app; handbrake is now the CLI-only formula.


πŸ”Š Audio

App Homebrew Description
FineTune finetune Per-app volume, audio routing and 10-band EQ in the menu bar

🎨 Design

App Homebrew Description
Figma figma Collaborative interface design tool

πŸ“· Photo

App Homebrew Description
RapidRAW – manual Non-destructive, GPU-accelerated RAW image editor

πŸ€– AI

App Homebrew Description
Comfy Desktop comfy Desktop app for ComfyUI β€” node-based image, video and audio generation
AIRI airi Self-hosted AI companion with realtime voice chat

πŸͺŸ Window Management

App Homebrew Description
Rectangle rectangle Window manager with keyboard shortcuts
Loop loop Elegant radial-menu window manager

πŸš€ Productivity

App Homebrew Description
Itsypad itsypad Tiny, fast scratchpad and clipboard manager
MarkEdit markedit Like TextEdit, but dedicated to Markdown

🧰 Menu Bar

App Homebrew Description
Hidden Bar hiddenbar Ultra-light utility to hide menu bar icons
MacTools mactools Free collection of native macOS menu bar tools
Vorssaint Utils vorssaint Menu bar toolkit β€” keep-awake, system monitor, volume mixer

⌨️ Keyboard

App Homebrew Description
KeyClu keyclu Keyboard shortcut cheat sheet overlay for any app
Keyty keyty Modern open-source keyboard and mouse input visualizer
KeyType – manual System-wide AI autocomplete for macOS

πŸ—‚ Files

App Homebrew Description
Spacedrive spacedrive Cross-platform file explorer on a virtual distributed filesystem
Pearcleaner pearcleaner Open-source app uninstaller and leftover cleaner

πŸ“¦ Archives

App Homebrew Description
Keka keka The macOS file archiver, supporting many formats

πŸ“₯ Downloads

App Homebrew Description
Ghost Downloader ghost-downloader Cross-platform multithreaded download manager

πŸ” Security

App Homebrew Description
Sentinel alienator88-sentinel Configure Gatekeeper, unquarantine and self-sign apps
LuLu lulu Open-source firewall that blocks unknown outgoing connections

⚠️ Use alienator88-sentinel. The plain sentinel cask is HashiCorp's policy-as-code tool.


πŸ“š Notes

App Homebrew Description
Obsidian obsidian Markdown-based personal knowledge base
Rook – manual Notes app built for code
Notion notion All-in-one workspace and notes

πŸ’° Finance

App Homebrew Description
Wealthfolio wealthfolio Private, local-first investment and net-worth tracker
Sure – self-hosted Personal finance app for everyone β€” a Ruby service you host yourself

πŸ’Ύ Boot Media

App Homebrew Description
macUSB macusb All-in-one bootable USB creator for Mac
MacToy – manual Native Ventoy installer and raw image flasher

πŸ“² Sideloading

App Homebrew Description
iloader iloader User-friendly iOS sideloading companion
Adobe Downloader – manual Downloader and installer for Adobe macOS apps

🐚 Shells

Tool Homebrew Description
Nushell nushell Modern shell with structured data pipelines

πŸ”§ CLI Tools

Tool Homebrew Description
bat bat cat clone with syntax highlighting
eza eza Modern replacement for ls
fd fd Fast, user-friendly find alternative
fzf fzf Command-line fuzzy finder
gh gh Official GitHub CLI
mas mas Mac App Store command-line interface

🌍 Web Apps

Not macOS apps and not on Homebrew β€” these run in a browser or as a service you host yourself. Listed here so the catalogue stays honest about what brew can and cannot install.

Project Stack Description
WorldMonitor TypeScript Real-time global intelligence dashboard β€” news aggregation and geopolitical monitoring
Osiris TypeScript Open-source real-time OSINT dashboard
OpenUI TypeScript The open standard for generative UI
Nuxt Studio TypeScript Edit your Markdown website in production
MiroFish Python Simple, universal swarm-intelligence prediction engine
Moodist TypeScript Ambient sounds for focus and calm
GeoLibre TypeScript Cloud-native GIS platform β€” browser, desktop, mobile and Jupyter
Pascal Editor TypeScript Create and share 3D architectural projects

Third-Party Taps

Port Killer is the only app here that lives outside homebrew/cask. Passing the full owner/tap/token path taps automatically, so no separate brew tap is needed.

brew install --cask productdevbook/tap/portkiller

Use the interactive install script to pick only what you need β€” no bloat, no surprises.

Contributors

Languages