How theoptimist/systemosaurus works
Project Type and Purpose
• Systemosaurus is a *configuration-management* project: it automates the installation and configuration of macOS (Darwin) machines via Nix, Nix-Darwin, Home-Manager, Homebrew and App Store (mas).
• Its goal is to bootstrap a new Mac: install toolchains, clone the repo, apply Nix configurations, and manage user dotfiles.
File Structure
Top-level directories reveal the architectural layers:
• config/ → Nix expressions for package installs & system services
• home/ → Home-Manager configurations for user dotfiles & tools
• modules/ → Reusable Nix modules to extend configurations
• profiles/ → Named configuration profiles (groups of settings)
• install → Bootstrapping script to kick off the process
• Nix files → configuration.nix, shell.nix, default.nix, platform-specific overrides
Extract Key Insights from the README
• The install script triggers:
• Installation of Command Line Tools, Nix, Nix-Darwin
• Invocation of darwin-rebuild to apply config/ and modules/
• Use of Home-Manager (home/) for user-level dotfiles
• Fallback on Homebrew and mas for packages not in Nix
• Layers: System (config + modules + profiles), User (home), External (Homebrew, mas).
Main Components
a. Bootstrap/Installer Layer
• install script (curl | bash)
• environment checks (CLT, Nix presence)
b. System Configuration Layer
• Nix Daemon & nix-darwin
• config/ directory (default.nix + per-platform overrides)
• modules/ (darwin modules, security modules, etc.)
• profiles/ groupings
c. User Configuration Layer
• Home-Manager (home/) with subfolders for shell, terminal, cloud, darwin-specific widgets
• Dotfiles & functions.sh, p10k.zsh, tmux.conf, kitty.conf
d. External Package Managers
• Homebrew
• mas (App Store CLI)
e. Underlying Platform
• macOS (Darwin)
• Unencrypted Nix store volume
Relationships and Data Flows
• Installer → Nix Daemon & nix-darwin
• nix-darwin → reads config/ + modules/ + profiles/ → builds /run/current-system
• home-manager → reads home/ → populates $HOME dotfiles & apps
• Both config & home layers may call out to external package managers (brew, mas) when needed
• All layers depend on the underlying macOS host
Architectural Patterns and Technologies
• Declarative configuration (Nix expressions)
• Layered approach: System vs. User vs. External
• Reusable modules (DRY) in modules/
• Profile-based grouping for different machine roles
• Imperative bootstrap (install script) transitioning into declarative management
Essential Architectural Elements
• Don’t just lump “config/” as a single block—show subdomains: packages, services, platform overrides
• Expose extensibility: where a new module or profile would integrate
• That both system and user layers are ultimately driven by Nix’s evaluation