Reusable NixOS, nix-darwin, and Home Manager configuration modules with a guide to building your own system. The repository also contains actively deployed Linux and macOS configurations as maintained examples.
Read the guide · Build the starter · Reuse a module
The public starter has its own pinned dependencies, Git and shell settings, and a disposable NixOS practice VM. It needs no personal credentials and does not activate anything on your account when you build it. The deployed workstations add desktop services, shared appearance, font selection, and host-managed secrets.
| Goal | Entry point |
|---|---|
| Learn through a working example | First configuration |
| Boot a configured Linux system | Console VM |
| Improve an existing configuration | Git, file search, prompt |
| Understand the desktop decisions | Themes and fonts |
| Find an independent package or framework | Related projects |
The starter declares x86 Linux, ARM Linux, and Apple Silicon macOS. Its serial VM is x86 Linux only. The support table distinguishes evaluation, native builds, and runtime evidence. The host definitions are hardware-specific deployed examples, not installation templates.
Shared theme settings cover application colors and font roles. These recorded Pango and Qt samples show multilingual text and emoji through two toolkits:
These are reviewed font-test captures, not current desktop screenshots. See the appearance guide for their context and the font reference for recorded checks.
If a guide step fails, use the guide feedback form. A useful reproduction helps improve the next reader's experience. If this project helps you, consider starring it so you can find it again.
| Location | Responsibility |
|---|---|
flake.nix |
Input pins, framework integration, supported systems, and public outputs |
hosts/ |
Operating-system targets, hardware, boot, and system policy |
homes/ |
Home profiles, selected applications, and user preferences |
modules/ |
Reusable NixOS, Darwin, Home Manager, and cross-platform features |
overlays/ |
Package selection and registered temporary upstream fixes |
lib/ |
Explicit shared helper exports, including checked script writers |
flake/ |
Deployment, development tools, and check composition |
tests/ |
Behavior tests, generated-output checks, and integration fixtures |
docs/ |
Operational guides and reviewed technical evidence |
pkgs/ |
Separate repository for package recipes |
nix-config-framework/ |
Separate repository for target discovery and module composition |
nix-seal/ |
Separate repository for secret-management implementation |
The last three directories are Git submodules. Clone with --recurse-submodules,
or run git submodule update --init --recursive in a fresh checkout.
See CONTRIBUTING.md before changing configuration.
The framework discovers targets beneath hosts/{nixos,darwin}/ and homes/.
Each target selects reusable features through the modules argument in its
default.nix. For example, desktop-envs-hyprland selects
modules/nixos/desktop-envs/hyprland.nix.
The framework also imports Nix files beneath each target's local/ directory.
These files must be modules; keep target-specific helper exports under the
module's lib option. Do not also list automatically imported files in the
target specification. Shared settings under homes/shared/ and hosts/shared/
are imported explicitly by their consumers. The host definitions are maintained
deployment examples; reusable behavior belongs in the shared modules and
features.
A reusable directory's default.nix controls its aggregate selection. Without
one, selecting the directory imports every Nix file below it. Adding a file to
such a directory can therefore change existing targets. Use an explicit
default.nix when a group needs a curated selection, and individual selectors
when targets need different features. See the
selector contract.
Hosts attach home profiles through homes.<login>.config. The framework owns
that integration and shares the host's package set with attached homes. Both
current home profiles require host-managed secret storage and set
standalone = false; build and activate them through their host.
See the secret-management guide.
Keep variations as typed options on the owning feature when behavior actually varies. The browser suite and desktop modules already use this approach. Use local settings for target policy, and keep reusable configuration beside its implementation. The existing repository split lets package recipes and the framework evolve without importing workstation policy.
Run nix develop for pinned development tools and just --list for commands.
Choose focused checks using the validation guide.
The push hook runs publication and security checks; it does not build every
flake check. Run broader checks when the changed behavior warrants them, while
CI distributes native checks across runners.
Evaluation, build, and activation establish different things; successful
evaluation alone does not validate a service at runtime.
Use . or an absolute checkout path as the flake reference. Nix then uses Git
source filtering, including tracked working-tree edits. Add intended new source
files with git add -N <file> or stage them before evaluation. An explicit
path: reference includes ignored local files too, so repository commands avoid
it. This distinction follows the
Nix flake reference rules.
Keep raw evidence and private material outside the checkout, as required by the
publication policy.
Run full desktop system builds on the desktop host. On that host, use
just os-build desktop to build or just os-switch desktop to build and
activate; both use the workload runner. From another machine,
just desktop-build builds remotely and performs dry activation, while
just desktop-deploy activates the remote result. Darwin builds and runtime
checks require a suitable Darwin host. See AGENTS.md for build
placement.