nix-me

Declarative macOS configuration made simple

Manage your entire Mac development environment as code.
No Nix knowledge required.

Overview

nix-me transforms macOS system configuration into a reproducible, version-controlled experience. Whether you're setting up a new machine or keeping multiple Macs in sync, nix-me makes it effortless.

What You Get

Interactive Setup Wizard - Clone from existing hosts or start fresh
Composable Profiles - Mix dev, work, and personal configs
Powerful CLI - nix-me command for all operations
Multi-Machine Support - MacBooks, Mac Minis, VMs
Reproducible Builds - Same config = same result
Rollback Safety - Undo any change instantly

How It Works

┌─────────────────────────────────────┐
│  Profiles (composable)              │
│  dev + work + personal              │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│  Machine Type                       │
│  macbook / macmini / vm             │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│  Nix Packages │ Homebrew │ App Store│
└─────────────────────────────────────┘

Quick Start

One-Line Install (No Clone Required)

Run directly from GitHub - no need to manually clone the repository:

curl -fsSL https://raw.githubusercontent.com/lucamaraschi/nix-me/main/install.sh | bash

The wizard will guide you through:

Clone or create - Copy settings from an existing host or start fresh
Select profiles - Choose dev, work, personal (or combine them)
Configure machine - Set hostname, type, and username
Build system - Apply your configuration

Time: 30-60 minutes (mostly package downloads)

Alternative Installation Methods

Download and inspect before running

# Download the installer
curl -fsSL https://raw.githubusercontent.com/lucamaraschi/nix-me/main/install.sh -o install.sh

# Review it
less install.sh

# Make executable and run
chmod +x install.sh
./install.sh

Install from a specific branch

# Use a different branch (e.g., dev, feature/xyz)
curl -fsSL https://raw.githubusercontent.com/lucamaraschi/nix-me/dev/install.sh | REPO_BRANCH=dev bash

Non-interactive installation

# Fully automated setup
curl -fsSL https://raw.githubusercontent.com/lucamaraschi/nix-me/main/install.sh | \
  NON_INTERACTIVE=1 bash -s -- hostname macmini "My Mac Mini" username

Arguments: hostname machine-type machine-name username

Prerequisites

Requirement	Details
macOS	10.15 Catalina or later
Architecture	Intel or Apple Silicon
Disk Space	~5GB free
Privileges	Admin access required

Profiles

Profiles are composable - combine them to match your needs:

Profile	What's Included	Use Case
`dev`	VS Code, Ghostty, Docker Node.js, Python, Go, Rust GitHub CLI, Xcode k3d, OrbStack, UTM	Software development
`work`	Slack, Teams, Zoom Notion, Linear, Miro Microsoft Office, Figma Terraform, kubectl, AWS CLI	Work collaboration
`personal`	Spotify, OBS yt-dlp, ffmpeg iA Writer	Entertainment & personal
`hacking`	Wireshark, Ghidra, Metasploit nmap, hashcat, aircrack-ng AirJack (auto-installed)	Security testing & CTFs
`maker`	Bambu Studio, Bambu Connect Fusion 360, Blender, FreeCAD OpenSCAD, MeshLab	3D printing & CAD

Profile Combinations

# Work developer (most common)
extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/work.nix
];

# Personal dev machine
extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/personal.nix
];

# Security researcher / pentester
extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/hacking.nix
];

# Maker / 3D printing station
extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/maker.nix
];

# Full setup (everything)
extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/work.nix
  ./hosts/profiles/personal.nix
  ./hosts/profiles/hacking.nix
  ./hosts/profiles/maker.nix
];

# Minimal (no profiles - just base essentials)
# Simply omit extraModules

The `nix-me` CLI

After installation, manage your system with the nix-me command:

Essential Commands

nix-me status          # System overview
nix-me switch          # Apply configuration changes
nix-me update          # Update all packages
nix-me diff            # Preview changes before applying

Package Management

nix-me add app slack   # Add a GUI application
nix-me add tool jq     # Add a CLI tool
nix-me list            # View installed packages
nix-me browse          # Interactive package browser

Configuration

nix-me setup           # Run setup wizard (with clone support)
nix-me customize       # Interactive customization menu
nix-me inspect         # TUI configuration explorer
nix-me doctor          # Diagnose issues

Architecture

nix-me/
├── flake.nix                 # Machine definitions & inputs
├── install.sh                # Interactive installer
│
├── bin/
│   └── nix-me                # CLI tool
│
├── hosts/
│   ├── types/
│   │   ├── shared/           # Common settings (all machines)
│   │   ├── macbook/          # MacBook optimizations
│   │   ├── macbook-pro/      # MacBook Pro optimizations
│   │   ├── macmini/          # Mac Mini optimizations
│   │   └── vm/               # VM optimizations
│   │
│   ├── profiles/             # Composable profiles
│   │   ├── dev.nix           # Development tools
│   │   ├── work.nix          # Work/collaboration apps
│   │   ├── personal.nix      # Entertainment/personal
│   │   ├── hacking.nix       # Security/pentesting tools
│   │   └── maker.nix         # 3D printing & CAD
│   │
│   └── machines/
│       └── [hostname]/       # Machine-specific overrides
│
├── modules/
│   ├── darwin/               # System-level (nix-darwin)
│   │   ├── apps/
│   │   │   └── installations.nix  # Base package lists
│   │   ├── core.nix
│   │   ├── system.nix
│   │   └── ...
│   │
│   └── home-manager/         # User-level (home-manager)
│       ├── apps/
│       │   ├── claude-code.nix   # Claude Code global settings
│       │   ├── git.nix
│       │   ├── ssh.nix
│       │   └── ...
│       └── shell/
│           └── fish.nix
│
├── lib/                      # Shell libraries
│   ├── ui.sh
│   ├── wizard.sh             # Setup wizard with clone support
│   ├── config-builder.sh     # Config generation
│   └── ...
│
└── tui/                      # React TUI (Configuration Inspector)
    └── src/

Machine Types

MacBook

Mac Mini

VM

Optimized for mobility:

Battery preservation
Trackpad gestures
Smaller dock icons
Power management

Optimized for desktop:

Multi-display support
Larger UI elements
Always-on performance
Tailscale networking
Professional tools (Adobe, Figma)
Docker & OrbStack

Optimized for testing:

Minimal packages
Reduced resources
Fast boot times
No App Store apps

Configuration

Adding a Machine

Option 1: Clone from Existing Host

nix-me setup
# Choose: [2] Clone settings from an existing host
# Select the source host
# The wizard copies machine type and profiles

Option 2: Interactive Wizard

nix-me setup
# Choose: [1] Create new configuration from scratch
# Select machine type, profiles, etc.

Option 3: Manual Configuration

Add to flake.nix:

"my-machine" = mkDarwinSystem {
  hostname = "my-machine";
  machineType = "macbook";     # or "macbook-pro", "macmini", "vm"
  machineName = "My MacBook";
  username = "yourusername";
  extraModules = [
    ./hosts/profiles/dev.nix   # Development tools
    ./hosts/profiles/work.nix  # Work apps
  ];
};

Customizing Packages

Per-machine customization in hosts/machines/[hostname]/default.nix:

{ ... }:
{
  apps = {
    useBaseLists = true;           # Inherit base packages

    # GUI apps (Homebrew Casks)
    casksToAdd = [ "figma" "notion" ];
    casksToRemove = [ "spotify" ];

    # CLI tools (Homebrew)
    brewsToAdd = [ "wget" ];

    # CLI tools (Nix)
    systemPackagesToAdd = [ "jq" ];

    # Mac App Store apps
    masAppsToAdd = {
      "Keynote" = 409183694;
      "Bear" = 1091189122;
    };
    masAppsToRemove = [ "Xcode" ];
  };
}

Example: Maker/Craft Station

A Mac Mini configured for 3D printing and creative work:

# hosts/machines/zion/default.nix
{ ... }:
{
  imports = [ ../../types/macmini/default.nix ];

  apps = {
    useBaseLists = true;
    casksToAdd = [
      "bambu-studio"        # 3D printer slicer
      "autodesk-fusion"     # Fusion 360 CAD
      "openscad"            # Programmable CAD
      "elgato-camera-hub"   # Streaming hardware
    ];
  };
}

Then in flake.nix:

"zion" = mkDarwinSystem {
  hostname = "zion";
  machineType = "macmini";
  machineName = "Zion";
  username = "youruser";
  extraModules = [
    ./hosts/profiles/dev.nix
    ./hosts/profiles/work.nix
    ./hosts/profiles/personal.nix
  ];
};

Display Configuration

Display auto-configuration is opt-in. To enable:

display.autoConfigureResolution = true;

This sets all displays to maximum resolution ("More Space") using displayplacer.

Fish Shell

nix-me configures Fish shell with powerful defaults:

Custom Functions

Function	Description
`mknode <name>`	Create Node.js project with Nix environment
`nixify`	Add Nix support to existing project
`mkcd <dir>`	Create directory and cd into it
`gst`, `gd`, `gcm`	Git shortcuts

Keyboard Shortcuts

Shortcut	Action
`Ctrl+T`	Fuzzy file search
`Ctrl+R`	Command history
`Ctrl+E`	Directory navigation

Auto-Pair

Automatically closes brackets and quotes: () [] {} "" ''

Claude Code Integration

nix-me configures Claude Code with global settings managed by Nix.

What's Configured

Global settings at ~/.claude/settings.json
Safe default permissions for common commands (git, nix, brew, npm)
Co-authored-by disabled by default

Customizing

Edit modules/home-manager/apps/claude-code.nix to modify global permissions:

permissions = {
  allow = [
    "Bash(git:*)"
    "Bash(nix:*)"
    # Add more...
  ];
};

Project-specific settings go in .claude/settings.json in each repo (gitignored by default).

1Password SSH Integration

nix-me configures SSH to use 1Password as your SSH agent.

Setup

Open 1Password 8 → Settings → Developer
Enable "Use the SSH agent"
Add SSH keys to 1Password
Configure keys for github.com access

Verify

ssh-add -l              # List available keys
ssh -T git@github.com   # Test GitHub connection

Troubleshooting

"primary username does not exist"

Set username explicitly in flake.nix:

username = "yourusername";  # Output of: whoami

Nix installation issues

Force reinstall:

FORCE_NIX_REINSTALL=1 ./install.sh

1Password SSH not working

Check the socket exists:

ls -la ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock

Set manually if needed:

export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

Configuration errors

make check                              # Validate config
darwin-rebuild switch --show-trace      # Detailed errors
sudo darwin-rebuild switch --rollback   # Rollback changes

"/etc files have unrecognized content" error

This happens when /etc/bashrc, /etc/zshrc, etc. were modified outside nix-darwin. The make switch command automatically backs these up now, but if you see this error:

# Manually backup the files
sudo mv /etc/shells /etc/shells.before-nix-darwin
sudo mv /etc/bashrc /etc/bashrc.before-nix-darwin
sudo mv /etc/zshrc /etc/zshrc.before-nix-darwin
sudo mv /etc/zshenv /etc/zshenv.before-nix-darwin

# Then retry
make switch

Diagnostics

nix-me doctor    # Run full diagnostics
nix-me status    # Quick system overview

FAQ

Do I need to know Nix?

No! The wizard and CLI handle everything. You can customize without touching Nix code.

Will this break my existing setup?

No. The installer backs up configurations, preserves existing apps, supports rollbacks, and can be completely removed.

How much disk space?

~1-5GB for the Nix store, shared between all packages.

Can I use this at work?

Yes, but check company policies. Requires admin privileges; all packages come from official repositories.

How do I backup my config?

It's all in git:

cd ~/.config/nixpkgs
git add . && git commit -m "My customizations" && git push

Can I have multiple profiles on one machine?

Yes! Profiles are composable. Combine dev + work, dev + personal, or all three:

extraModules = [
  ./hosts/profiles/dev.nix
  ./hosts/profiles/work.nix
  ./hosts/profiles/personal.nix
];

Can I clone settings from another machine?

Yes! Run nix-me setup and choose "Clone settings from an existing host". The wizard will copy the machine type and profiles from your selected source host.

Advanced Usage

Non-Interactive Installation

# Full automation
NON_INTERACTIVE=1 ./install.sh hostname macbook "My Mac" username

# Environment variables
FORCE_NIX_REINSTALL=1    # Force Nix reinstall
SKIP_BREW_ON_VM=1        # Skip Homebrew in VMs
REPO_BRANCH=dev          # Use specific branch

Make Commands

make switch    # Apply configuration
make update    # Update flake inputs
make check     # Validate configuration
make build     # Build without applying
make help      # Show all commands

Contributing

Contributions welcome!

Fork the repository
Create a feature branch
Test with make check && make build
Submit a pull request

Acknowledgments

Built on the shoulders of giants:

nix-darwin - macOS system management
Home Manager - User environment management
Mitchell Hashimoto's config - Inspiration

Need help? Run nix-me doctor
Want to customize? Run nix-me customize

_{MIT License • Made with Nix}

Name		Name	Last commit message	Last commit date
Latest commit History 109 Commits
.claude		.claude
.vscode		.vscode
bin		bin
config/vscode		config/vscode
docs		docs
hosts		hosts
lib		lib
modules		modules
overlays		overlays
scripts		scripts
tests		tests
tui		tui
.gitattributes		.gitattributes
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation

nix-me

Overview

What You Get

How It Works

Quick Start

One-Line Install (No Clone Required)

Alternative Installation Methods

Prerequisites

Profiles

Profile Combinations

The nix-me CLI

Essential Commands

Package Management

Configuration

Architecture

Machine Types

Configuration

Adding a Machine

Customizing Packages

Display Configuration

Fish Shell

Custom Functions

Keyboard Shortcuts

Auto-Pair

Claude Code Integration

What's Configured

Customizing

1Password SSH Integration

Setup

Verify

Troubleshooting

Diagnostics

FAQ

Advanced Usage

Non-Interactive Installation

Make Commands

Contributing

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

The `nix-me` CLI

Packages