max-baz dotfiles, a NixOS and Wayland configuration to read and fork

A whole desktop, not a folder of themes

The description is short, configuration for NixOS, sway, kitty, helix, zsh and more, and the primary language of the repository is Nix, which tells you how the thing is built. This is not a collection of colour schemes and shell aliases. It is a system configuration expressed as a Nix flake, with the directory layout to match: flake.nix and flake.lock at the root, a hosts/ directory for the per machine outputs, a modules/ directory for the reusable pieces, an overlay/ directory for custom package overrides, and a util/ directory for helper scripts. The audience is a developer on NixOS who wants to see how a working Wayland desktop is put together, or who wants to lift a specific part of it. The README's own framing is instructive, since it invites you to explore the repository and incorporate what you like into your own setup, and to open an issue or a pull request with questions and suggestions. It is a personal configuration offered as a reference, and reading it as documentation is the more sensible way to consume it.

The tools it assembles into one desktop

The README lists the tools the author uses, develops or helps maintain, and the list is the fastest way to understand the configuration's character. The window manager is sway with waybar for the status bar, both on Wayland. The terminal is kitty, described as a fast GPU-accelerated terminal, and the editor is helix, a modular text editor with multiple cursors. The shell stack is zsh with powerlevel10k and zsh4humans, described in the README as terminal superpower, and the visual theme across all the applications is the dark variant of Gruvbox. Around that are the pieces that are less common and more interesting. yubikey-touch-detector is a tool the author wrote to detect when a YubiKey is waiting for a touch, which solves the problem of an unresponsive key during a login, and wluma is another of the author's tools, automatic brightness adjustment based on screen contents. browserpass is a browser extension for pass and gopass, which is how password management reaches the desktop, and the JoyPixels font provides colourful emojis for Linux applications. The last entry is about system integrity rather than appearance, with arch-secure-boot for UEFI Secure Boot on Arch Linux and snap-pac for btrfs snapshots during a system update, and the topic list confirms the shape with asahi, btrfs, firefox, git, home-manager, nix-flake, powerlevel10k, waybar, wayland and yubikey.

Flake layout: hosts, modules, overlay and a private half

The four directories are the architecture of the configuration, and each one has a job. hosts/ holds the per machine definitions, which is what a flake needs in order to produce a different output for a laptop and a desktop, and the justfile refers to the hostname when it switches the home manager, so the host name is the selector. modules/ holds the reusable configuration, the kind of piece you would copy into your own system, and overlay/ holds custom package overrides for things that are not in nixpkgs. util/ holds helper scripts. The configuration is split across two repositories, which is the detail with a practical consequence. The justfile operates on both $HOME/.dotfiles and $HOME/.dotfiles-private, and the update target even has a separate recipe for the private flake, so the public repository is only the public half of the setup. That is a reasonable design for a person with secrets, and it is a complication for anyone adopting the configuration as it stands, since the private repository is not something you can clone.

The justfile is the interface you actually touch

Rather than asking you to remember flake commands, the repository wraps them in a justfile, and the recipes are short enough to read. The default target is switch, and it is defined per operating system. On Linux it rebuilds the NixOS system.

sudo nixos-rebuild switch --flake $HOME/.dotfiles --impure

On macOS it uses nix-darwin instead.

nix run -- nix-darwin switch --flake $HOME/.dotfiles

A trace recipe exists for debugging, and it simply passes the show-trace flag through to the switch recipe. The home recipe switches the home manager for the current host.

nix run -- home-manager switch --flake $HOME/.dotfiles#$(hostname)

The update recipe is the one with a security detail in it, because it hands a GitHub token to the flake updater so that private inputs can be fetched.

nix flake update --option access-tokens "github.com=$(gh auth token)"

The two helper recipes at the bottom are the automation around the rest. git-commit-flakes commits a changed flake.lock with the message update flakes, and git-add marks everything as intent-to-add in both the public and the private dotfiles repository, so that a rebuild sees the new files.

Fork it, because there is no release to pin

The README says something that should be read before anything is installed, and it is a recommendation to fork the repository rather than use it directly, because the author is changing things on a daily basis. The repository confirms this. There are no GitHub releases, so there is no version to track, and the last push was on 2026-10-18, which is a snapshot rather than a distribution. For a dotfiles repository this is less alarming than it would be for a library, since the artefact is a configuration you are going to edit anyway, but it does have two consequences. The first is that the recommended installation route is a fork under your own account, which means the flake references in your configuration point at your fork rather than at the upstream, and you inherit the update cadence whether you want it or not. The second is that the private repository problem becomes immediate, since the justfile's helpers operate on $HOME/.dotfiles-private, which does not exist in a fork and has to be created or the recipes adjusted.

What to take from it, and what to leave

The realistic use cases are two. The first is reading, where a working combination of sway, kitty, helix, zsh, waybar and powerlevel10k in one tree is worth more than any of them documented alone, and the module boundaries make it possible to see how the author composes them. The second is selective adoption, which is what the README asks for, incorporating what you like into your own setup, ideally with the same flake mechanism if you already run Nix. The alternative is a home-manager configuration of your own, which is the same technology without inheriting someone else's opinions about key bindings, the terminal font and the password manager, and the difference in practice is that home-manager gives you the machinery while this repository gives you a specific machine. The third option, using your distribution's package manager and a handful of dotfiles in your home directory, is less capable and considerably easier to reason about, and for a machine you already know how to maintain it is often the right call. The failure mode to avoid is installing the whole thing on a system you do not understand, because a NixOS rebuild replaces the system configuration rather than adding to it.

Editorial conclusion

This configuration fits a developer who runs NixOS with Wayland and wants a working reference for sway, kitty, helix and zsh rather than a theme to install, and it fits someone who wants to read how the pieces fit together in a real system. It does not fit a user who wants a stable base to track, because there are no releases and the author says the tree changes daily, and it does not fit someone who has no Nix at all, since the whole configuration is a flake. Verify three things first: that your machine can host a NixOS or nix-darwin setup, since the switch recipes rebuild the system rather than installing a package, whether the private dotfiles repository it references is something you have to replace, and that you are willing to fork, because the README says to and because an unpinned daily-changing tree is not something to depend on directly.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. max-baz/dotfiles on GitHub
4. README