yutkat/dotfiles: a NixOS and Arch desktop where the layer that links your files is mise

What is actually in the repository

The description is the inventory. The editor is Neovim, the shell is zsh with zinit and powerlevel10k, the terminal is WezTerm, and the desktop is Hyprland with walker and dunst. The operating systems are NixOS, which is recommended, and Arch Linux, with Ubuntu, Fedora and CentOS named in the description as well.

The tree shows how the pieces are arranged. There is `nixos/` and `home-manager/` for the two layers of Nix configuration, a `flake.nix` and `flake.lock` at the root, `mise.toml` for the tool and dotfile layer, `neovim.yml` for the editor tooling, `install.sh` for the bootstrap, and `system-etc/` for system level configuration.

Then there are the hidden directories that carry the actual configuration, `.config/`, `.local/`, `.mise/` and `.nvim/`, along with the shell and editor startup files `.zshenv`, `.xinitrc` and `.xprofile`. There are also `.claude/` and `.codex/` directories, which are the agent configuration directories, and `AGENTS.md` for the instructions to an assistant working in the repository, alongside a `.devcontainer/` directory and a `selene.toml` for Lua linting.

The languages in the project follow the tools, with Lua as the primary language because of the Neovim configuration, and the repository describes itself plainly as my home dotfiles. The `overview` image at the top of the README is the desktop as it actually looks, which is the most efficient way to decide whether this is a setup you would enjoy living in.

The NixOS path, which is the recommended one

The NixOS install is nine steps and the ordering is the point, because each step depends on the previous one having produced a working toolchain.

You clone the repository and change into it, then edit the configuration. The instruction is to open `flake.nix` and edit the `myHosts` block, which is where the per host settings live. Then `./install.sh` installs nix with the flake support, and `sudo nixos-rebuild switch --flake .#<hostname>` builds the system with your hostname selected from the flake.

The dotfiles are then linked, and this is the step that is different from a typical dotfiles repository. The linking is managed by the `[dotfiles]` section in `mise.toml`, and you run:

mise trust
mise bootstrap dotfiles apply

`mise trust` is the mechanism by which mise is allowed to execute the tasks in a configuration you have just cloned, and `mise bootstrap dotfiles apply` is the task that links the files. After that, `exec zsh` starts a new shell so the zsh plugin manager, zinit, installs its plugins, `mise run setup` installs the mise managed tools and runs the setup tasks, and the Neovim plugins are installed with a headless sync:

vi --headless -c 'Lazy! sync' -c 'qall'

That last command is the lazy.nvim idiom, and running it headless is what makes it usable in a bootstrap script.

The NixOS path is the one the project recommends, and it is the only one where the whole configuration is a pure function of the flake, which is the property that makes a dotfiles setup reproducible rather than merely organised.

The dotfiles layer is a mise task, not a symlink script

The mechanism behind the linking step is worth understanding on its own, because it is the part that differs from most dotfiles repositories and it is reusable regardless of the rest of the stack.

The `[dotfiles]` section of `mise.toml` defines the task, and the property the README calls out is that link sources are relative to the repository root, so any clone location works without extra configuration. That is a small decision with a large effect on how often you have to edit your configuration after moving a repository, and it is the kind of detail that only appears in a project that has been moved a few times.

The same two commands appear in every install path, on NixOS, on other systems with Nix, on the without-Nix path and in the Docker path, which tells you that the dotfiles layer is a separate concern from the system configuration. The system configuration is Nix and Home Manager, and the dotfiles are mise.

That separation is also why the without-Nix path is described as CLI-only, with the note that Nix-managed extras such as the Neovim egress sandbox are not available there.

The paths that do not use Nix, and the Docker one for a trial

There are two more install paths, and the shorter one is the most honest description of what the project expects.

The first is for other systems that still have Nix. The steps are the same up to the Home Manager switch, and the first run uses the locked Home Manager, with `home-manager switch` available afterwards. The command is:

nix run --inputs-from . home-manager -- switch --flake .#<hostname>

and if you override the user name, the invocation adds `--impure`, because the configuration then depends on a value that cannot be known at evaluation time:

NIX_USERNAME=your_username nix run --inputs-from . home-manager -- switch --impure --flake .#<hostname>

The second path avoids Nix entirely and is CLI-only, with mise and the OS package manager doing the work. The prerequisites are `git`, `zsh`, `curl`, `gcc`, `make`, `unzip`, `node` at version 22 or later, and `bun`, because mise installs npm based tools with bun. The README warns that distribution Node.js packages can be too old, on Ubuntu for example, and to use the official installer in that case. The path is explicitly not tested in CI.

The last path is a temporary install in a container, which is the right way to evaluate somebody else's desktop configuration without dirtying your home directory:

docker run -it --rm archlinux:latest /bin/bash

Inside, you install sudo and git, create a test user with a passwordless sudo rule, switch to it, clone the repository, and run the single-user install:

./install.sh --single

The `exec bash` after it, and the Home Manager switch against the `test` host, follow from the same steps as the full install, which is a neat way to try the whole system without touching your own machine.

The stack and the key bindings

The components list is short, which is worth noting for a dotfiles repository, since most of them accumulate a dozen layers. There is zsh, neovim, wezterm, and optionally Hyprland.

The keyboard tables are a good summary of the design, because they show a consistent modifier vocabulary. In WezTerm, Alt with h, j, k or l switches window, Alt and j closes a window, Alt and k creates one, and Shift with the arrows switches pane. In Hyprland, the Super modifier with h, j, k or l switches window, Super and Shift moves the window, and Super, Ctrl and Shift moves the workspace.

So the pattern is that the modifier alone is a spatial navigation, and adding Shift moves the thing rather than going to it. That kind of consistency is what you cannot get from assembling a configuration out of other people's parts, and it is the actual content of a dotfiles repository.

For the shell, the stack is zsh with zinit as the plugin manager and powerlevel10k for the prompt, which is the most common combination in this ecosystem, and the Neovim side uses lazy.nvim, given the sync command in the install steps and the `neovim.yml` file in the tree.

Where this configuration is the wrong choice

The first wrong case is a machine that will never have Nix. Even the path that avoids Nix still installs mise, still expects a specific set of build tools, and still gives you a configuration where a piece, the Neovim egress sandbox, is simply absent. The configuration is opinionated and the opinions are about the system layer, so a partial adoption is a partial experience.

The second is a team environment. This is explicitly a personal setup, my home dotfiles, and it assumes one machine, one user and a willingness to have your shell, editor, terminal and compositor configured by someone else's choices. Sharing it means inheriting a single person's taste in every layer at once.

The third is a machine that is not Linux, or a Linux distribution that is not in the list. The supported matrix is NixOS and Arch for the graphical setup, and NixOS and Arch for the command line, with other distributions supported only through Nix or mise and explicitly not tested in CI. On macOS or Windows the paths described simply do not apply.

The fourth is an expectation of a stable configuration. The releases are numbered in an unusual scheme, 49.154 on 2026-06-06, 50.004 on 2026-06-11 and 51.024 on 2026-07-09, which suggests a versioning tied to something other than a public release convention, and the last push was on 2026-10-15, so the repository is active and changes frequently. Pinning a commit is the only way to make it reproducible, and the Nix flake lock is what makes the system layer reproducible while the dotfiles layer stays live.

Editorial conclusion

Adopt this configuration as a reference if you already run NixOS or Arch with Neovim, zsh and a Wayland compositor, since the value is in a coherent, working set of configurations rather than in the individual files. Do not adopt it if you want a quick editor theme or a shell prompt, because every install path assumes mise, and most of them also put Nix and Home Manager on your machine. Verify first that you are on the supported platforms, NixOS or Arch for the graphical setup, that you edit the `myHosts` block in `flake.nix` before building, and that you understand the Neovim egress sandbox is a Nix-managed extra that the without-Nix path does not give you.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. yutkat/dotfiles on GitHub