Dotfiles

Declarative, reproducible, multi-platform development environment powered by Nix Flakes, Home Manager, and nix-darwin.

One config to rule them all -- macOS, Linux, and NixOS.

Highlights

Declarative -- Entire environment defined in code, version controlled, reproducible
Any Linux box -- Headless-safe base + opt-in profiles work on NixOS and foreign distros (Ubuntu, etc.), desktop or headless server
Multi-platform -- Single flake manages macOS (via nix-darwin), Linux, and NixOS
Multi-host -- Per-machine config with shared modules, platform abstractions, and composable role profiles
Stylix -- Consistent theming across applications (Kanagawa scheme, via the wayland profile)
Make-driven -- Simple commands that auto-detect your host

Structure

.
├── flake.nix                  # Main flake entry point (inputs, outputs, host wiring, profileRegistry)
├── flake.lock                 # Flake lock file
├── nix/                       # Nix & Home Manager configs
│   ├── lib.nix                # Host builders + profile folding + common (user info, paths, env)
│   ├── checks.nix             # CI checks (formatting, deadnix, statix) and formatter
│   ├── home.nix               # Shared, headless-safe base (imports all shared modules)
│   ├── hosts/                 # Per-machine config only
│   │   ├── mac-machine/       #   macOS (aarch64-darwin) + nix-darwin
│   │   └── nixos/             #   NixOS (x86_64-linux) full system + host overrides
│   ├── modules/               # Cross-platform, headless-safe HM modules (explicitly imported)
│   │   ├── file/              #   File symlinks (ctags, tmuxinator, scripts)
│   │   ├── packages/          #   Shared CLI packages
│   │   ├── programs/          #   Program configurations
│   │   ├── sessionpath/       #   PATH management
│   │   └── sessionvariables/  #   Environment variables
│   ├── profiles/              # Opt-in role bundles, selected via `profiles = [ ... ]`
│   │   ├── graphical/         #   GUI apps (cross-platform + linux/ gated via common.isLinux)
│   │   └── wayland/           #   Hyprland/Niri/Noctalia session (HM side) + stylix
│   ├── platforms/             # OS-family abstractions
│   │   ├── darwin/            #   macOS: Karabiner, Hammerspoon
│   │   │   └── modules/       #   opt-in: Aerospace, JankyBorders
│   │   └── linux/             #   headless-safe stub (Linux-universal user config)
│   └── docs/                  # Setup guides
│       ├── 1password-setup.md #   1Password SSH & GPG setup
│       └── sops-setup.md      #   Encrypted secrets (sops-nix, age) bootstrap & workflow
│
├── nvim/                      # Neovim configuration (Lua, live-linked via HM)
├── tmuxinator/                # tmuxinator project templates (live-linked via HM)
├── git/                       # Git ignore + template (store snapshots via HM)
├── niri/                      # Niri compositor config (live-linked via HM)
├── noctalia/                  # Noctalia settings.toml (live-linked into XDG state)
├── scripts/                   # Utility scripts (tmux project launchers, theme switchers)
├── agents/                    # Global AI-agent guidance, skills, and language conventions
├── ctags/                     # Universal Ctags config (symlinked via HM)
├── macosx/                    # macOS-specific configs (Karabiner, Hammerspoon)
├── misc/                      # Legacy configs (archived)
│
├── Makefile                   # Convenience commands
└── AGENTS.md                  # AI agent instructions

Supported Hosts

Host	Platform	Architecture	Management	Profiles
`mac-machine`	macOS	aarch64-darwin	nix-darwin + Home Manager	`graphical`
`nixos`	NixOS	x86_64-linux	NixOS + Home Manager	`graphical`, `wayland`

Any other Linux box -- a foreign distro desktop, or a headless VPS -- can be added as a standalone Home Manager target (mkHomeConfiguration); the base is headless-safe and graphical bits are opt-in via profiles. See Adding a New Host.

Quick Start

# Clone
git clone https://github.com/zekzekus/dotfiles ~/devel/tools/dotfiles
cd ~/devel/tools/dotfiles

# Apply (auto-detects host)
make darwin    # macOS (nix-darwin + Home Manager)
make nixos     # NixOS full system rebuild
make home      # Standalone Home Manager only (NixOS or any foreign Linux distro)

See nix/README.md for detailed installation instructions.

Commands

make help          # Show all commands with detected host
make home          # Switch standalone Home Manager (Linux; not used on Darwin)
make home-build    # Plan standalone Home Manager (dry-run, does not build)
make darwin        # Rebuild nix-darwin + integrated Home Manager (macOS only)
make darwin-build  # Build nix-darwin without switching
make nixos         # Rebuild NixOS + integrated Home Manager (NixOS only)
make nixos-build   # Plan NixOS (dry-run, does not build)
make update        # Update flake inputs + pinned package versions
make check         # Run all checks (format, deadnix, statix)
make fmt           # Format all Nix files with alejandra
make clean         # Clean build artifacts

Architecture

Every host is built from one headless-safe base and then specialised along three orthogonal axes -- OS family, role, and management target. The base (home.nix + modules/* + platforms/linux) ships no GUI apps or desktop services, so it runs on a headless server just as happily as a laptop; anything graphical is opt-in via a profile.

                  ┌────────────────────────────────────────────┐
                  │              flake.nix                     │
                  │ inputs - profileRegistry - host wiring     │
                  └────────────────────────────────────────────┘
                                         │
                ┌────────────────────────────────────────────────┐
                │            lib.nix builders                    │
                │ mkNixosSystem / mkDarwinSystem /               │
                │ mkHomeConfiguration                            │
                │ pick management target:                        │
                │ nixos | generic-linux | standalone             │
                └────────────────────────────────────────────────┘
                                         │  assemble the HM module stack
                                         ▼
        ┌─────────────────────────────────────────────────────────────────┐
        │ hosts/<host>/             machine-specific overrides            │
        ├─────────────────────────────────────────────────────────────────┤
        │ profiles = [ ... ]        graphical, wayland          (role)    │
        ├─────────────────────────────────────────────────────────────────┤
        │ platforms/{darwin,linux}  auto-selected by system   (OS family) │
        ├─────────────────────────────────────────────────────────────────┤
        │ home.nix + modules/*      shared, HEADLESS-SAFE base            │
        └─────────────────────────────────────────────────────────────────┘

Three orthogonal axes

OS family -- platforms/{darwin,linux}, auto-selected from system.
Role -- profiles/*, opt-in per host via profiles = [ ... ] (e.g. graphical, wayland), resolved from the profileRegistry in flake.nix. A profile may bundle HM modules, system modules, and extra specialArgs.
Management target -- the builder (mkNixosSystem / mkDarwinSystem / mkHomeConfiguration) plus mkHomeConfiguration's target (nixos | generic-linux | standalone), which drives non-NixOS integration. On a foreign distro it auto-selects generic-linux and enables targets.genericLinux.

How lib.nix assembles a host (module order)

home.nix -- shared, headless-safe base (imports every shared modules/*)
platforms/darwin or platforms/linux -- auto-selected by system
profile modules from profiles = [ ... ] -- resolved via the profileRegistry
hosts/<hostname>/default.nix -- host-specific Home Manager overrides

The centralized common attrset (user info, paths, env vars, isLinux/isDarwin) is passed as specialArgs to every Home Manager and system module. Live-edited configs (Neovim, Niri, Noctalia, agents) use mkOutOfStoreSymlink. Ghostty and tmux are Nix-managed. Script helpers are store snapshots of repo-relative sources.

What's Included

Base (all hosts -- headless-safe)

Neovim (nixpkgs unstable) with Treesitter grammars, LSPs for Lua, Nix, Go, Rust, Python, TypeScript, Ruby, Clojure, Haskell
Fish & Nushell with Starship prompt, Carapace completions
tmux with tmuxinator
Git with delta, difftastic, lazygit, jujutsu (jj), lazyjj, jjui
direnv, atuin (shell history), zoxide, yazi
ripgrep, fd, bat, btop, fastfetch
GPG signing, SSH via 1Password agent (encrypted host list via sops-nix)
devenv

graphical profile (opt-in -- any host with a display)

Ghostty terminal, Obsidian (cross-platform)
Linux adds: Chromium, Zed, Emacs (pgtk), OBS Studio (PipeWire capture), Radicle, media viewers, helium (x86_64), 1Password GUI autostart

wayland profile (opt-in -- Wayland desktop, normally paired with graphical)

Hyprland and Niri compositors with Noctalia shell, hypridle, hyprlock
Stylix CLI theming (Kanagawa, dark polarity); Plasma owns shared Qt/GTK appearance
rofi launcher, Hyprland polkit agent
Tray/session services: clipboard history (cliphist), automount (udiskie), network + Tailscale applets

darwin platform (macOS via nix-darwin)

Aerospace tiling window manager (opt-in)
JankyBorders for window highlights (opt-in, currently disabled)
Karabiner-Elements key remapping
Hammerspoon automation
Homebrew integration via nix-homebrew (Raycast, Zed, 1Password)
Touch ID for sudo

nixos host (system level)

PipeWire audio, Bluetooth, SDDM login, Plasma 6, Niri, and Hyprland sessions
Kanata key remapping (caps-lock as ctrl/esc)
Steam + Gamescope gaming, gpu-screen-recorder, v4l2loopback virtual camera
Flatpak (GeForce NOW), Podman (Docker-compatible)
Tailscale VPN, OpenSSH (reachable via Tailscale only)
1Password (NixOS module + GUI polkit), xdg portals (KDE/Hyprland/GTK/GNOME)

Flake Inputs

Input	Purpose
`nixpkgs`	Main package set (nixos-unstable)
`home-manager`	User environment management
`sops-nix`	Encrypted secrets (age-backed), wired into the base in `nix/lib.nix`
`nix-darwin`	macOS system management
`nix-homebrew`	Declarative Homebrew on macOS
`homebrew-emacs-plus`	Homebrew tap for emacs-plus (macOS)
`hyprland`	Wayland compositor
`stylix`	System-wide theming
`practicalli-clojure-cli-config`	Clojure CLI user config (deps.edn aliases)
`nix-flatpak`	Declarative Flatpak management
`determinate`	Determinate Nix integration

Documentation

Home Manager README -- Installation, adding hosts, troubleshooting
1Password Setup -- SSH agent & GPG key management
sops Setup -- Encrypted secrets bootstrap & workflow (sops-nix, age)

License

MIT

Navigation Menu

Repository files navigation

Dotfiles

Highlights

Structure

Supported Hosts

Quick Start

Commands

Architecture

What's Included

Flake Inputs

Documentation

License

About

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents		.agents
agents		agents
ctags		ctags
git		git
macosx		macosx
misc		misc
niri		niri
nix		nix
noctalia		noctalia
nvim		nvim
scripts		scripts
secrets		secrets
tmuxinator		tmuxinator
zed/themes		zed/themes
.envrc		.envrc
.gitignore		.gitignore
.gitmodules		.gitmodules
.sops.yaml		.sops.yaml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix

Latest commit

History

Folders and files

Repository files navigation

Dotfiles

Highlights

Structure

Supported Hosts

Quick Start

Commands

Architecture

What's Included

Flake Inputs

Documentation

License

About

Resources

Stars

Watchers

Forks

Used by

Contributors

Languages