Hey, you made it! Welcome. 🤓
Nix is a powerful package manager for Linux and Unix systems that ensures reproducible, declarative, and reliable software management.
This repository contains configuration for a general-purpose development environment that runs Nix on MacOS, NixOS, or both simultaneously.
I use it daily on my 🧑🏻💻 M1 Macbook Pro and an x86 PC in my home office. It also runs as a VM on your Mac. Many others have reported that it's working for them too.
The benefit is that you'll define your work environment once, and then you're done, forever and ever. Something broken? Just chill, nixpkgs community will fix it. Welcome to the side of Github that has your back.
Check out the starter templates and step-by-step commands below to get started!
- Overview
- Layout
- Features
- Disclaimer
- Videos
- Installing
- How to Create Secrets
- Live ISO
- Deploying Changes to Your System
- Compatibility and Testing
- Contributing
- Feedback and Questions
- License
- Appendix
.
├── apps # Nix commands used to bootstrap and build configuration
├── hosts # Host-specific configuration
├── modules # MacOS and nix-darwin, NixOS, and shared configuration
├── overlays # Drop an overlay file in this dir, and it runs. So far, mainly patches.
├── templates # Starter versions of this configuration
- Nix Flakes: 100% flake driven, no
configuration.nix, no Nix channels─ justflake.nix - Same Environment Everywhere: Easily share config across Linux and Mac (both Nix and Home Manager)
- MacOS Dream Setup: Fully declarative MacOS, including UI, dock and MacOS App Store apps
- Simple Bootstrap: Simple Nix commands to start from zero, both x86 and MacOS platforms
- Managed Homebrew: Zero maintenance homebrew environment with
nix-darwinandnix-homebrew - Disk Management: Declarative disk management with
disko, say goodbye to disk utils - Secrets Management: Declarative secrets with
agenixfor SSH, PGP, syncthing, and other tools - Super Fast Emacs: Bleeding edge Emacs that fixes itself, thanks to a community overlay
- Built In Home Manager:
home-managermodule for seamless configuration (no extra clunky CLI steps) - NixOS Environment: Extensively configured NixOS including clean aesthetic + window animations
- Nix Overlays: Auto-loading of Nix overlays: drop a file in a dir and it runs (great for patches!)
- Declarative Sync: No-fuss Syncthing: managed keys, certs, and configuration across all platforms
- Emacs Literate Configuration: Large Emacs literate configuration to explore (if that's your thing)
- Simplicity and Readability: Optimized for simplicity and readability in all cases, not small files everywhere
- Backed by Continuous Integration: Flake auto updates weekly if changes don't break starter build
Installing Nix on MacOS will create an entirely separate volume. It will exceed many gigabytes in size.
Some folks don't like this. If this is you, turn back now!
Note
Don't worry; you can always uninstall Nix later.
Build.mov
- GUI
Emacs.mov
- Terminal
Emacs_Terminal.mov
NixOS.mp4
Important
Note: Nix 2.18 currently has a bug that impacts this repository.
For now, if you run into errors like this:
error: path '/nix/store/52k8rqihijagzc2lkv17f4lw9kmh4ki6-gnugrep-3.11-info' is not valid
Run nix copy to make the path valid.
nix copy --from https://cache.nixos.org /nix/store/52k8rqihijagzc2lkv17f4lw9kmh4ki6-gnugrep-3.11-info
I've tested these instructions on a fresh Macbook Pro as of January 2024.
xcode-select --installThank you for the installer, Determinate Systems!
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- installChoose one of two options
Simplified version without secrets management
- Great for beginners, enables you to get started quickly and test out Nix.
- Forgoring secrets means you must configure apps that depend on keys, passwords, etc., yourself.
- You can always add secrets later.
mkdir -p nixos-config && cd nixos-config && nix flake --extra-experimental-features 'nix-command flakes' init -t github:dustinlyons/nixos-config#starterFull version with secrets management
- Choose this to add more moving parts for a 100% declarative configuration.
- This template offers you a place to keep passwords, private keys, etc. as part of your configuration.
mkdir -p nixos-config && cd nixos-config && nix flake --extra-experimental-features 'nix-command flakes' init -t github:dustinlyons/nixos-config#starter-with-secretsfind apps/aarch64-darwin -type f \( -name apply -o -name build -o -name build-switch -o -name create-keys -o -name copy-keys -o -name check-keys \) -exec chmod +x {} \;Run this Nix app to replace stub values with your username, full name, and email.
nix run .#applyNote
If you're using a git repository, only files in the working tree will be copied to the Nix Store.
You must run git add . first.
You can search for packages on the official NixOS website.
Review these files
modules/darwin/casks.nixmodules/darwin/packages.nix-
modules/nixos/packages.nix modules/shared/packages/nix
Add anything from your existing ~/.zshrc, or just review the new configuration.
Review these files
If you are using the starter with secrets, there are a few additional steps.
In Github, create a private nix-secrets repository. You'll enter this name during installation.
Before generating your first build, these keys must exist in your ~/.ssh directory. Don't worry, I provide a few commands to help you.
| Key Name | Platform | Description |
|---|---|---|
| id_ed25519 | MacOS / NixOS | Used to download secrets from Github. |
| id_ed25519_agenix | MacOS / NixOS | Used to encrypt and decrypt secrets. |
You must run one of these commands:
This command auto-detects a USB drive connected to the current system.
Keys must be named
id_ed25519andid_ed25519_agenix.
nix run .#copy-keysnix run .#create-keysNote
If you choose this option, make sure to save the value of id_ed25519.pub to Github.
cat /Users/$USER/.ssh/id_ed25519.pub | pbcopy # Add to clipboardIf you're rolling your own, just check they are installed correctly.
nix run .#check-keysFirst-time installations require you to move the current /etc/nix/nix.conf out of the way.
[ -f /etc/nix/nix.conf ] && sudo mv /etc/nix/nix.conf /etc/nix/nix.conf.before-nix-darwinNote
If you're using a git repository, only files in the working tree will be copied to the Nix Store.
You must run git add . first.
Then, if you want to ensure the build works before deploying the configuration, run:
nix run .#buildFinally, alter your system with this command:
nix run .#build-switchWarning
On MacOS, your .zshrc file will be replaced with the zsh configuration from this repository. So make some changes here first if you'd like.
This configuration supports both x86_64 and aarch64 platforms.
Download and burn the minimal ISO image to a USB, or create a new VM with the ISO as base.
If you're building a VM on an Apple Silicon Mac, choose 64-bit ARM.
Quick Links
Boot the installer.
If you are using the starter with secrets, there are a few additional steps.
In Github, create a private nix-secrets repository. You'll enter this name during installation.
Before generating your first build, these keys must exist in your ~/.ssh directory. Don't worry, I provide a few commands to help you.
| Key Name | Platform | Description |
|---|---|---|
| id_ed25519 | MacOS / NixOS | Used to download secrets from Github. |
| id_ed25519_agenix | MacOS / NixOS | Used to encrypt and decrypt secrets. |
You must one run of these commands:
This command auto-detects a USB drive connected to the current system.
Keys must be named
id_ed25519andid_ed25519_agenix.
sudo nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#copy-keyssudo nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#create-keysIf you're rolling your own, just check they are installed correctly.
sudo nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#check-keysAfter the keys are in place, you're good to go. Run either of these commands:
Important
For Nvidia cards, select the second option, nomodeset, when booting the installer, or you will see a blank screen.
Caution
Running this will reformat your drive to the ext4 filesystem.
Simple
- Great for beginners, enables you to get started quickly and test out Nix.
- Forgoring secrets means you must configure apps that depend on keys or passwords yourself.
- You can always add secrets later.
sudo nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#installWith secrets
- Choose this to add more moving parts for a 100% declarative configuration.
- This template offers you a place to keep passwords, private keys, etc. as part of your configuration.
sudo nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#install-with-secretsOn first boot at the login screen:
- Use the shortcut
Ctrl-Alt-F2(orFn-Ctrl-Option-F2if on a Mac) to move to a terminal session - Login as
rootusing the password created during installation - Set the user password with
passwd <user> - Go back to the login screen:
Ctrl-Alt-F7
To create a new secret secret.age, first create a secrets.nix file at the root of your nix-secrets repository.
Note
secrets.nix is interpreted by the imperative agenix commands to pick the "right" keys for your secrets.
This file is not read when building your configuration.
secrets.nix
let
user1 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH";
users = [ user1 ];
system1 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE";
systems = [ system1 ];
in
{
"secret.age".publicKeys = [ user1 system1 ];
}Now that we've configured agenix with our secrets.nix, it's time to create our first secret. Run the command below. Note, it assumes your SSH private key is in ~/.ssh/ or you can provide the -i flag with a path to your id_ed25519 key.
EDITOR=vim nix run github:ryantm/agenix -- -e secret.age
This opens an editor to accept, encrypt, and write your secret to disk.
Commit the file to your nix-secrets repo and add a reference in the secrets.nix of your nix-secrets repository. References look like
{
"secret.age".publicKeys = [ user1 system1 ];
}
where "secret.age" is your new filename. Now we have two files: secrets.nix and our secret.age. Let me show you.
Let's say I wanted to create a new secret to hold my Github SSH key.
I would cd into my nix-secrets repo directory, verify the agenix configuration (named secrets.nix) exists, then run
EDITOR=vim nix run github:ryantm/agenix -- -e github-ssh-key.age
This would start a vim session.
I would enter insert mode :i, copy+paste the key, hit Esc and then type :w to save it, resulting in the creation of a new file, github-ssh-key.age.
Then, I would edit secrets.nix to include a line specifying the public key to use for my new secret. I specify a user key, but I could just as easily specify a host key.
secrets.nix
let
dustin = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH";
users = [ dustin ];
systems = [ ];
in
{
"github-ssh-key.age".publicKeys = [ dustin ];
}Finally, I'd commit all changes to the nix-secrets repository, go back to my nixos-config and run nix flake update to update the lock file.
The secret is now ready to use. Here's an example from my configuration. In the end, this creates a symlink to a decrypted file in the Nix Store that reflects my original file.
Not yet available. Coming soon.
nix run --extra-experimental-features 'nix-command flakes' github:dustinlyons/nixos-config#liveWith Nix, changes to your system are made by
- editing your system configuration
- building the system closure
- creating and switching to it (i.e creating a new generation)
nix run .#build-switchnix flake updateThis configuration has been tested and confirmed working on the following platforms:
- M1/M2/M3 Apple Silicon
- Bare metal x86_64 PC
- NixOS inside VMWare on MacOS
- MacOS Sonoma inside Parallels on MacOS
Interested in contributing to this project? Here's how you can help:
-
Code Contributions: If you're interested in contributing code, please start by looking at open issues or feature requests. Fork the repository, make your changes, and submit a pull request. Make sure your code adheres to the existing style. For significant changes, consider opening an issue for discussion before starting work.
-
Reporting Bugs: If you encounter bugs or issues, please help by reporting them. Open a GitHub Issue and include as much detail as possible: what you were doing when the bug occurred, steps to reproduce the issue, and any relevant logs or error messages.
Have feedback or questions? Feel free to use the discussion forum.
This project is released under the MIT License.
Reasons to jump into flakes and skip nix-env, Nix channels, etc
- Flakes work just like other package managers you already know:
npm,cargo,poetry,composer, etc. Channels work more like traditional Linux distributions (like Ubuntu), which most devs don't know. - Flakes encapsulate not just project dependencies, but Nix expressions, Nix apps, and other configurations in a single file. It's all there in a single file. This is nice.
- Channels lock all packages to one big global
nixpkgsversion. Flakes lock each individual package to a version, which is more precise and makes it much easier to manage overall. - Flakes have a growing ecosystem (see Flake Hub or Dev Env), so you're future-proofing yourself.
| Component | Description |
|---|---|
| Window Manager | Xorg + bspwm |
| Terminal Emulator | alacritty |
| Bar | polybar |
| Application Launcher | rofi |
| Notification Daemon | dunst |
| Display Manager | lightdm |
| File Manager | thunar |
| Text Editor | emacs daemon mode |
| Media Player | cider |
| Image Viewer | feh |
| Screenshot Software | flameshot |
"All we have to decide is what to do with the time that is given us." - J.R.R. Tolkien