* feat(agents): use the shell's own dialect; allow 5 s retry backoff Assisted-by: DeepSeek Harness (deepseek-flash) * feat(dsh): make Nushell the only shell Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): wait for CI in the background Pushes to a PR often start multi-minute CI runs, and an agent that holds the turn open on a foreground watch reports nothing until it ends. Require the pushed head and running checks to be reported first, the watch to run in the background, and the result to be collected after independent work or after ending the turn. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): keep the shell-handoff rule platform-neutral The global rules carry no Windows assumptions: drop the cmd, pwsh, and wsl handoff examples and keep the POSIX forms plus the dsh refusal. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(dsh): keep the shell-swap docs POSIX-only This repository manages Linux and Darwin hosts, not Windows: drop the Windows handoff examples and terminal-backend wording from dsh.md. The home patch also disabled pwsh-sandbox redundantly because dsh-base already disables that row on POSIX; keep only the active bash-sandbox disable and verify the composed rows with --dump-config. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): keep the global rules runtime-neutral Global rules are loaded by every agent CLI, so they must not describe one runtime's behavior. Drop the dsh-specific sentence and wording while keeping the expectation to prefer Nushell structured pipelines and Python. Runtime behavior stays documented in home/base/tui/agents/dsh.md. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): default shell work to Nushell Keep the Nushell preference explicit in the runtime-neutral global rules, and keep runtime behavior in runtime docs. Bash stays a narrow fallback for tasks Nushell cannot do. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): tighten global-rule scope and CI guidance Keep global rules runtime- and project-neutral, and state that boundary in the file. Remove the duplicated CI turn-steering text in favour of the Communication rule, resolve the watch run before watching instead of relying on gh pr checks --watch alone, name the working-directory parameter generically, and distinguish a bounded retry backoff from a fixed completion wait. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): never estimate a CI run's duration A CI run has no predictable length, so do not turn "it looks short" into a reason to wait. The rule is unconditional: report the head and started checks, start a background watch, and end the turn; collect the result on completion. The eval scenario now uses an unknown duration. Assisted-by: DeepSeek Harness (deepseek-flash) * docs(agents): move maintenance guidance to the README The runtime/project boundary is guidance for editing the rules, not a rule agents need loaded every session. The README's Maintaining global rules section already owns that audience; the loaded rules keep only behavior. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(dsh): render the home patch from a YAML template Move the home-layer cordis patch into dsh-cordis.patch.yml, substitute the bundle and Nushell store paths with replaceVars, and link the rendered file through home.file.source. This module is the only writer of ~/.dsh/cordis.patch.yml, the current host has no such file, and the profile patch is a separate layer. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(dsh): install the shell plugin through NUR withPlugins Replace the local runCommand bundle, peer symlink, and home-layer YAML file with the plugin package and dsh.withPlugins from ryan4yin/nur-packages#43. The package wrapper adds a generated --patch overlay after the profile layer, so dsh no longer writes or manages ~/.dsh/cordis.patch.yml. The NUR input is temporarily pinned to the PR branch and its commit; point it back at main once the NUR PR merges. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): expose the NUR package set as nurPkgs Pass one per-system NUR package set through specialArgs instead of repeating nur-ryan4yin.packages.${pkgs.stdenv.hostPlatform.system} at each call site. The agents, rime, and idols-ruby modules now use the short binding. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): use nurPkgs in package overlays The overlays receive specialArgs too, so they can use the per-system NUR package set instead of rebuilding the long input path from prev. This leaves only the definition in outputs/default.nix. Assisted-by: DeepSeek Harness (deepseek-flash) * refactor(nix): name the per-system NUR set myNurPkgs Leave room for consuming another NUR repository later, and match the existing mylib/myvars naming. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): consume the merged NUR package set nur-ryan4yin now points at main after ryan4yin/nur-packages#43 was squash merged; the lock records the merge commit. No branch ref remains. Assisted-by: DeepSeek Harness (deepseek-flash) * fix(dsh): pass the web profile explicitly The withPlugins launcher prepends --patch, which historically prevented dsh from auto-expanding "dsh web" into "--profile web". Pass the profile explicitly in the Just recipe and the verification commands so they work with both plain dsh and the wrapper. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): pick up the wrapped-profile fix Update nur-ryan4yin to the squash merge that keeps an implicit profile name first, so "dsh web" and "just dsh-web" work through the wrapper again. Assisted-by: DeepSeek Harness (deepseek-flash) * chore(dsh): pick up the plugin peer-link fix Update nur-ryan4yin to the squash merge that links the dsh peer tree at node_modules/@deepseek-ai instead of nesting it one level deeper. This is the import failure that stopped nushell-executor from activating after deploy. Assisted-by: DeepSeek Harness (deepseek-flash)
❄️ Ryan4Yin's Nix Config ❄️
My configuration is becoming more and more complex, and it will be difficult for beginners to read. If you are new to NixOS and want to know how I use NixOS, I would recommend you to take a look at the ryan4yin/nix-config/releases first, check out to some simpler older versions, such as i3-kickstarter, which will be much easier to understand.
This repository is home to the Nix code that builds all of my systems:
- NixOS desktops — Home Manager, Niri (Wayland), the Noctalia shell, agenix.
- macOS desktops — nix-darwin + Home Manager, sharing the same
home/configuration with the NixOS desktops. - NixOS servers — three physical mini PCs running the VMs (libvirt and microVMs), the K3s test cluster and the self-hosted services.
See ./hosts for the host inventory, ./outputs for how the flake outputs are composed, ./BACKUP.md for the backup design, and ./AGENTS.md for the repository conventions.
Why NixOS & Flakes?
Nix allows for easy-to-manage, collaborative, reproducible deployments. This means that once something is setup and configured once, it works (almost) forever. If someone else shares their configuration, anyone else can just use it (if you really understand what you're copying/referring now).
As for Flakes, refer to Introduction to Flakes - NixOS & Nix Flakes Book
Want to know NixOS & Flakes in detail? Looking for a beginner-friendly tutorial or best practices? You don't have to go through the pain I've experienced again! Check out my NixOS & Nix Flakes Book - 🛠️ ❤️ An unofficial & opinionated 📖 for beginners!
If you're using macOS, check out ryan4yin/nix-darwin-kickstarter for a quick start.
Components
| NixOS (Wayland) | |
|---|---|
| Display Manager | greetd + tuigreet |
| Window Manager | Niri |
| Desktop Shell | Noctalia — bar/notifications/launcher/lock screen/control center/power menu/screenshots, one native shell |
| Terminal Emulators | Kitty, Ghostty |
| Terminal Multiplexer | tuios |
| Shell | Nushell + Starship |
| Editors / IDE | Zed (GUI, primary), VS Code (GUI); Helix (TUI, primary), Neovim (TUI, backup) |
| Color Scheme | catppuccin-nix |
| Networking | systemd-networkd / NetworkManager |
| Input Method | Fcitx5 + rime + 小鹤音形 flypy |
| System Monitor | Btop (+ Noctalia's built-in sysmon widgets) |
| File Manager | Yazi (TUI) + thunar (GUI) |
| Media Player | mpv |
| Image Viewer | imv |
| Screenshots | Native Noctalia capture: region / fullscreen / display picker, with a built-in annotation editor |
| Screen Recording | OBS, gpu-screen-recorder, wf-recorder |
| Fonts | Nerd fonts |
| Filesystem & Encryption | tmpfs as /, Btrfs subvolumes on a LUKS encrypted partition for persistent data; unlock via passphrase |
| Secure Boot | lanzaboote |
Wallpapers: https://github.com/ryan4yin/wallpapers
Screenshots
Editors / IDE
- Terminal editors: ./home/base/core/editors/ — Helix / Neovim,
$EDITOR, docs. - GUI editors: Zed (primary) and VS Code.
- LLM coding agents: ./agents — rules, installers, CLI snippets; see ./agents/README.md.
Secrets Management
See ./secrets for details.
Security & Hardening
See ./SECURITY.md for the threat model, security architecture, controls and audit status, ./hardening/README.md for application sandboxing and Linux hardening, and ./WORKAROUNDS.md for temporary exceptions and known gaps.
How to Deploy this Flake?
🔴 IMPORTANT: You should NOT deploy this flake directly on your machine ❗ It will not succeed. This flake contains my hardware configuration (such as hardware-configuration.nix, Nvidia support, etc.) which is not suitable for your hardware, and requires my private secrets repository ryan4yin/nix-secrets to deploy. You may use this repo as a reference to build your own configuration.
Updating flake inputs and rolling the result out safely is a procedure, not a single command. Follow
.agents/skills/nix-config-update/SKILL.md.
For NixOS:
To deploy this flake from NixOS's official ISO image (purest installation method), please refer to ./nixos-installer/
# Desktops: deploy the <hostname>-niri nixosConfiguration (e.g. ai-niri, shoukei-niri)
just niri # equals `sudo nixos-rebuild switch --flake .#<hostname>-niri`
just niri boot # set as the next boot configuration without switching
just niri switch debug # detailed output
# Other hosts (servers, VMs): deploy the nixosConfiguration matching the bare hostname
just local
just local boot
just local switch debug
For macOS (nix-darwin):
# If you are deploying for the first time,
# 1. install nix & homebrew manually.
# 2. prepare the deployment environment with essential packages available
nix shell nixpkgs#just nixpkgs#nushell
# 3. comment home-manager's code in lib/macosSystem.nix to speed up the first deployment.
# Deploy the darwinConfiguration by hostname match (fern, frieren)
just local
just local debug # detailed output (macOS has no switch/boot mode)
Remote / cluster hosts are deployed with Colmena on top
of the same flake, e.g. just col <tag>, just k3s-test, just lab.
What y'all will need when Nix drives you to drink. (copy from hlissner's dotfiles, it really matches my feelings when I first started using NixOS...)
Validation & Development
nix develop provides the formatters and linters used by the repository. The most useful commands:
just test # eval tests across Linux & Darwin (fails unless the result is `true`)
just fmt # format all Nix files with nixfmt
just --list # all recipes
nix flake check # broader flake checks
For Nix changes, run just test and inspect just fmt's diff before committing. Non-Nix files are
formatted with prettier; spelling is checked with typos.
References
Other dotfiles that inspired me:
- Nix Flakes
- NixOS-CN/NixOS-CN-telegram
- notusknot/dotfiles-nix
- xddxdd/nixos-config
- bobbbay/dotfiles
- gytis-ivaskevicius/nixfiles
- davidtwco/veritas
- gvolpe/nix-config
- Ruixi-rebirth/flakes
- fufexan/dotfiles: gtk theme, xdg, git, media, etc.
- nix-community/srvos: a collection of opinionated and sharable NixOS configurations for servers
- Modularized NixOS Configuration
- Neovim / AstroNvim
- maxbrunet/dotfiles: astronvim with nix flakes.
- Misc


