Unified Nix flake for macOS hosts, Home Manager user configuration, and reusable module building blocks.
The repository still targets George's machines, user profile, and workflows. Ongoing work separates those personal defaults into reusable framework primitives and a standalone module library.
flowchart TD
flake["flake.nix<br/>inputs and outputs"] --> darwin["darwin/<br/>host entrypoints"]
flake --> home["home/<br/>user configuration"]
flake --> modules["modules/<br/>reusable modules"]
flake --> packages["packages/<br/>standalone derivations"]
flake --> overlays["overlays/<br/>package overrides"]
flake --> lib["lib/<br/>Python tooling and Nix helpers"]
lib --> cli["nixcfg.py<br/>Typer CLI"]
cli --> update["update<br/>source and hash refresh"]
cli --> ci["ci<br/>crate2nix and CI helpers"]
cli --> schema["schema<br/>codegen and verification"]
packages --> hosts["darwinConfigurations<br/>argus, rocinante, zeus"]
overlays --> hosts
modules --> hosts
home --> homecfg["homeConfigurations.george"]
modules --> homecfg
Read docs/architecture.md for the full layout and the output inventory. Read docs/README.md for the documentation index.
- Primary focus is nix-darwin plus Home Manager.
- Active Darwin hosts:
argusandzeus(work profile enabled), plusrocinante(personal profile). - Active Home Manager output:
homeConfigurations.george. - Exported systems:
aarch64-darwin,aarch64-linux,x86_64-linux. - NixOS modules are exported, but no
nixosConfigurationsexist today.
| Host | System | Profile |
|---|---|---|
argus |
aarch64-darwin |
work |
zeus |
aarch64-darwin |
work |
rocinante |
aarch64-darwin |
personal |
-
Install vanilla Nix with the official multi-user installer:
curl -L https://nixos.org/nix/install | sh -s -- --daemonThen open a new terminal, or load the daemon profile in the current shell:
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh -
Clone this repository to
~/.config/nixcfg. -
Bootstrap nix-darwin with an explicit host. The pre-switch macOS hostname is not declarative yet:
cd ~/.config/nixcfg sudo /nix/var/nix/profiles/default/bin/nix \ --extra-experimental-features 'nix-command flakes' \ run --inputs-from . nix-darwin#darwin-rebuild -- \ switch --flake .#zeus
-
After the first successful switch, use the managed
nhcommand for normal updates:nh darwin switch --no-nom .#zeus
Build the host outputs without applying them:
nix build .#checks.aarch64-darwin.darwin-argus
nix build .#checks.aarch64-darwin.darwin-rocinante
nix build .#checks.aarch64-darwin.darwin-zeus
nix build .#homeConfigurations.george.activationPackage# Enter the dev environment (tooling plus pre-commit hooks)
nix develop
# Keep Python tooling in sync for editor and test workflows
uv sync
# Format, then evaluate. The default no-build pass checks the current system.
# The all-systems pass is the full purity matrix. Neither may inspect outputs.
nix fmt
nix flake check --no-build --option allow-import-from-derivation false
nix flake check --all-systems --no-build --option allow-import-from-derivation false
nix flake check
# Pre-commit hooks
prek run -a
# Python test suite and coverage floor
uv run pytest
uv run coverage run -m pytest
uv run coverage reportRead docs/development.md for the full validation ladder and the Python test philosophy.
| Document | Contents |
|---|---|
| docs/README.md | Documentation index and reading paths |
| docs/architecture.md | Repository layout, flake outputs, module layers |
| docs/framework.md | Downstream reuse and the public API |
| docs/development.md | Dev shell, formatting, tests, quality gates |
| docs/packaging.md | Package discovery, crate2nix packages, app packaging |
| docs/source-modifications.md | Policy for editing upstream source trees |
| docs/appearance.md | macOS appearance bridging for terminal tools |
| docs/update/README.md | Update subsystem overview |
| docs/update/ci.md | Update workflow on hosted builders |
| docs/update/runtime.md | Durable execution, scheduling, and observability |
| docs/update/safety.md | Executable safety invariants for nixcfg update |
Updates and package-artifact maintenance are explicit CLI operations. The Update workflow prepares and validates one candidate on hosted macOS ARM64, Linux ARM64, and Linux x86_64 builders. It then proposes the validated changes in a pull request.
nix run .#nixcfg -- --help
nix run .#nixcfg -- update --help
nix run .#nixcfg -- ci --help
nix run .#nixcfg -- schema --helpEvery run that changes the checkout first builds all configured root
closures. A root closure contains a system or Home Manager configuration and all
its dependencies. A candidate identical to the checkout changes nothing, so it
skips the build gate. Root discovery follows darwin/*.nix, nixos/*.nix, and
home/*/default.nix. It does not require a separate list of host names.
Use nixcfg update --repair codex TARGET for one bounded local repair attempt.
Use --check to keep the result unapplied, and --patch PATH to export it.
Resume an interrupted run with nixcfg update --resume RUN_ID. Report the latest
run with nixcfg update --status [RUN_ID].
Read docs/update/README.md for the pipeline, and docs/update/safety.md for the invariants that govern promotion.
This flake can serve as a module framework for another repository. Public API
version 2 removes the site-specific nixcfgProfiles exports and the
mkDarwinHost.work policy shortcut. It also stops importing sops-nix through
mkHomeModules.
Site-specific policy, such as cache keys, org profile settings, and host or user modules, belongs in the consuming repository. The shared modules stay generic.
Read docs/framework.md for the exported module sets, the constructors, and a downstream example.