nixcfg

Unified Nix flake for macOS hosts, Home Manager user configuration, and reusable module building blocks.

This repository is still tailored to George's machines, user profile, and workflows today. Ongoing work is focused on separating those personal defaults into reusable framework primitives and a standalone library of modules.

Current state

• Primary focus is nix-darwin plus Home Manager.
• Active Darwin hosts: argus (work profile enabled) and rocinante (personal profile).
• Active Home Manager output: homeConfigurations.george.
• Exported systems: aarch64-darwin, aarch64-linux, x86_64-linux.
• NixOS modules are exported, but there are currently no nixosConfigurations defined.

Repository layout

• darwin/: host entrypoints.
• home/: user configuration (home/george).
• modules/: reusable modules (common, darwin, nixos, home).
• packages/: custom package outputs (axiom-cli, codex-desktop, conductor, droid, gogcli, homebrew-zsh-completion, linear-cli, nix-manipulator, scratch, sculptor, sublime-kdl, superset, toad).
• overlays/: package overrides and source pinning.
• lib/: Python libraries for update tooling and Nix model/schema helpers.
• nixcfg.py: Typer CLI exposed through nix run .#nixcfg -- ....

Install and apply

1. Install Nix (recommended: Determinate Nix Installer).
2. Clone this repository to ~/.config/nixcfg.
3. Apply the Darwin configuration:

nh darwin switch --no-nom .

Useful build-only checks:

nix build .#checks.aarch64-darwin.darwin-argus
nix build .#checks.aarch64-darwin.darwin-rocinante
nix build .#homeConfigurations.george.activationPackage

Day-to-day commands

# Enter the dev environment (tooling + pre-commit hooks)
nix develop

# Keep Python tooling in sync for editor/test workflows
uv sync

# Format and evaluate
nix fmt
nix flake check

# Pre-commit hooks
prek run -a

# Individual quality checks
uv run coverage run -m pytest
uv run coverage report

# Python test suite
uv run pytest

# Mutation testing with cosmic-ray
uv run cosmic-ray init cosmic-ray.toml .cosmic-ray.sqlite
uv run cosmic-ray exec cosmic-ray.toml .cosmic-ray.sqlite
uv run cr-report .cosmic-ray.sqlite

Update tooling

Updates and package-artifact maintenance are explicit CLI operations; the repository does not track GitHub Actions workflows.

nix run .#nixcfg -- --help
nix run .#nixcfg -- update --help
nix run .#nixcfg -- ci --help
nix run .#nixcfg -- schema --help

Reuse as a framework

This flake can be consumed by another repository as a module framework. Public API version 2 removes the site-specific nixcfgProfiles exports and the mkDarwinHost.work policy shortcut. It also stops importing sops-nix through mkHomeModules. Downstream configurations should import their own profile modules and, when needed, the sops-nix Home Manager module explicitly. Cache policy is now opt-in: the common substituter and trusted-key options default to empty lists. mkDarwinHost also enables the Rosetta builder by default without consulting ambient CI state; CI and other callers without a Linux builder must pass enableRosettaBuilder = false explicitly.

• Exported darwinModules, nixosModules, and homeModules are declared in lib/exports.nix, the canonical module inventory.

• Exported constructors in lib:

  • mkSystem, mkDarwinHost, mkHome, mkHomeModules, mkSetOpencodeEnvModule

• Downstream-oriented controls:

  • mkHome supports extraSpecialArgs for downstream-only module arguments
  • mkSystem supports extraSpecialArgs, homeManagerExtraSpecialArgs, and homeModuleArgsByUser. Darwin systems require at least one user; userless NixOS systems set primaryUser = null.
  • mkDarwinHost forwards extraSpecialArgs, homeManagerExtraSpecialArgs, and homeModuleArgsByUser; it also supports includeDefaultUserModule = false, homeModulesByUser, and a custom system.
  • default.nix and its mkLib helper accept an explicit evaluationContext for update source overrides and fake-hash evaluation. Ambient environment variables do not alter the API.

• Policy knobs intended to be overridden in downstream repos:

  • nixcfg.common.hostname
  • nixcfg.common.nix.substituters
  • nixcfg.common.nix.trustedPublicKeys
  • nixcfg.darwin.homebrew.{user,taps,mutableTaps,enableRosetta}

Example downstream pattern:

{
  outputs = { nixcfg, ... }: {
    darwinConfigurations.my-host = nixcfg.lib.mkDarwinHost {
      user = "alice";
      includeDefaultUserModule = false;

      extraSpecialArgs = {
        org = "acme";
      };
      homeManagerExtraSpecialArgs = {
        privateRoot = ./.;
      };
      homeModuleArgsByUser.alice = {
        role = "platform";
      };

      extraHomeModules = [
        nixcfg.homeModules.nixcfgGit
        ./home/alice.nix
      ];

      extraSystemModules = [
        {
          nixcfg.common.nix.substituters = [ "https://cache.nixos.org" ];
          nixcfg.common.nix.trustedPublicKeys = [
            "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
          ];
        }
      ];
    };
  };
}

Site-specific policy (for example cache keys, org profile settings, host/user modules) should live in the consuming repository, while these shared modules stay generic.

License

MIT