Skip to main content
This guide will help you get started with the configuration framework. Choose your platform below and follow the installation steps.
This is a personal configuration. Before deploying, you’ll need to:
  • Replace encrypted secrets in the secrets/ directory with your own
  • Modify host configurations to match your hardware
  • Adjust user settings and preferences

​
Prerequisites

Before you begin, ensure you have:
  • Basic familiarity with Nix and the Nix language
  • Git installed on your system
  • For NixOS: A working NixOS installation or the lilith ISO
  • For macOS: macOS with Nix or Lix installed
  • For WSL: Windows with WSL2 enabled

​
Choose your platform

Select the platform you want to install on:

NixOS

Install on a NixOS system

macOS

Install on macOS with nix-darwin

WSL

Install on Windows Subsystem for Linux

​
NixOS installation

There are two approaches to installing on NixOS: using the custom lilith ISO or performing a manual installation. The lilith ISO is a custom NixOS installer that includes the iznix-install script for easy deployment.
1

Download the ISO

Build the ISO locally or download it from the releases page:
# Build locally
nix build github:isabelroses/dotfiles#images.lilith
Or download from the releases page.
2

Boot from the ISO

Create a bootable USB drive using the ISO and boot your system from it.
# Example using dd (replace /dev/sdX with your USB drive)
sudo dd if=result/iso/*.iso of=/dev/sdX bs=4M status=progress
3

Run the installer

Once booted, run the iznix-install script included in the ISO:
iznix-install
Follow the prompts to configure your installation.
4

Reboot and customize

After installation completes, reboot into your new system and customize as needed.

​
Option 2: Manual installation

If you prefer to install manually or already have NixOS installed:
1

Install NixOS

If you don’t have NixOS yet, follow the official installation guide.
2

Clone the repository

Clone this configuration to ~/.config/flake:
git clone https://github.com/isabelroses/dotfiles.git ~/.config/flake
cd ~/.config/flake
3

Configure your host

Create a new host configuration or modify an existing one in systems/:
# systems/myhost/default.nix
{
  imports = [
    ./hardware.nix
    ./users.nix
  ];
  
  garden = {
    profiles = {
      graphical.enable = true;
      workstation.enable = true;
    };
    
    device = {
      cpu = "amd";  # or "intel"
      gpu = "amd";  # or "nvidia", "intel"
      keyboard = "us";
    };
    
    system.boot.loader = "systemd-boot";
  };
}
4

Add your host to the flake

Register your host in systems/default.nix:
hosts = {
  # ... existing hosts ...
  myhost = { };
};
5

Build and switch

Apply your configuration:
sudo nixos-rebuild switch --flake ~/.config/flake#myhost
Or use the included justfile:
just switch

​
Dual boot with Windows

If you’re setting up dual boot with Windows and want secure boot:
1

Enable secure boot in your config

garden.system.boot.secureBoot = true;
2

Locate the Windows EFI partition

lsblk -o NAME,FSTYPE,SIZE,MOUNTPOINT
3

Mount and copy Windows EFI files

sudo mkdir /mnt/winboot
sudo mount /dev/nvme0n1p1 /mnt/winboot  # adjust device path
sudo rsync -av /mnt/winboot/EFI/Microsoft/ /boot/EFI/Microsoft/
4

Clean up

sudo umount /mnt/winboot
sudo rmdir /mnt/winboot
Follow the lanzaboote quick start guide for additional secure boot setup.

​
macOS installation

Install the configuration on macOS using nix-darwin.
1

Install Lix

Install Lix (a Nix implementation) if you haven’t already:
curl -sSf -L https://install.lix.systems/lix | sh -s -- install
2

Enter a development shell

Clone the repository and enter a development shell to access required tools:
git clone https://github.com/isabelroses/dotfiles.git ~/.config/flake
cd ~/.config/flake
nix develop
3

Configure your host

Create or modify a darwin host configuration in systems/. See systems/tatsumaki/ for an example:
# systems/mymac/default.nix
{
  imports = [ ./users.nix ];
  
  garden = {
    profiles = {
      laptop.enable = true;
      graphical.enable = true;
      workstation.enable = true;
    };
  };
}
Add it to systems/default.nix:
hosts = {
  mymac = {
    arch = "aarch64";  # or "x86_64"
    class = "darwin";
  };
};
4

Provision the system

Run the provision command to set up nix-darwin:
just provision mymac
This will:
  • Install nix-darwin
  • Apply your configuration
  • Remove the non-declarative Lix installation
5

Rebuild for updates

After the initial provision, use the standard rebuild command:
just switch
On macOS, some GUI applications are installed via Homebrew (managed declaratively) because they’re not available in nixpkgs or work better as native .app bundles.

​
WSL installation

Install the configuration on Windows Subsystem for Linux.
1

Install NixOS-WSL

Follow the NixOS-WSL installation guide to get a basic NixOS environment running in WSL.
2

Clone the repository

git clone https://github.com/isabelroses/dotfiles.git ~/.config/flake
cd ~/.config/flake
3

Configure your WSL host

The valkyrie host is a WSL configuration example. Create your own or modify it:
# systems/mywsl/default.nix
{
  imports = [ ./users.nix ];
  
  garden = {
    profiles = {
      headless.enable = true;  # or graphical if using WSLg
    };
  };
}
Register it as a WSL host:
hosts = {
  mywsl = {
    class = "wsl";
  };
};
4

Build and switch

sudo nixos-rebuild switch --flake ~/.config/flake#mywsl
# or
just switch

​
Post-installation steps

After installing on any platform, you’ll want to:
1

Set up secrets

Replace the encrypted secrets with your own using SOPS. See the secrets management guide for details.
2

Customize your user configuration

Modify home/isabel/ (or create your own user directory) to customize:
  • Shell configuration
  • Editor settings
  • Application preferences
  • Package lists
3

Configure imperative services

Some services require manual login after installation:
# GitHub CLI
gh auth login

# Atuin (shell history sync)
atuin login
4

Explore the justfile

The repository includes a justfile with helpful commands:
just  # list all commands
just switch  # rebuild and switch
just update  # update flake inputs
just clean  # clean old generations

​
Useful commands

Here are some commands you’ll use frequently: 
# Rebuild and switch to new configuration
just switch

# Test configuration without switching
just test

# Update flake inputs
just update

# Update specific input
just update nixpkgs

# Build the ISO
just iso lilith

# Clean old generations
just clean

# Check flake for errors
just check

# Start a repl for a host
just repl-host myhost

​
Next steps

Now that you have the configuration installed, explore these topics:

Profiles

Learn about the available system profiles and how to use them

Modules

Discover the modular components you can enable or disable

Configuration

Deep dive into customizing your system configuration

Secrets

Set up encrypted secrets management with SOPS

​
Troubleshooting

​
Build fails with secret errors

The repository includes encrypted secrets that won’t work for you. Either:
  • Remove secret references from your host configuration
  • Set up your own secrets using SOPS

​
Module not found errors

Make sure your host is properly registered in systems/default.nix and you’ve run the rebuild command from the repository root.

​
macOS provision fails

Ensure you have Lix installed and are running the provision command from within nix develop.

​
Need more help?

Check the GitHub repository for issues and examples, or review the NixOS documentation for general Nix questions.

Build docs developers (and LLMs) love

Get started for freeTalk to us