nixpkgs-matrixai

Matrix AI public Nix package and module distribution flake.

This repository exists to provide one coherent producer interface for Matrix AI Nix consumers.

Without this layer, teams consume many independent flakes directly and drift over time on pins, output shapes, and composition behavior. Here, curation is intentionally centralized so downstream repositories can depend on one stable contract instead of many floating contracts.

In short:

• this repo owns what is distributed and how it is composed,
• downstream repos own environment-specific rollout and runtime operations.

Technical contract summary:

• public API is the outputs shape in flake.nix,
• canonical constructor path is lib.mkPkgs,
• constrained builtins.getFlake is allowed only under policy (path allowlist, commit pinning, and check enforcement).

Allowlist metadata is maintained in checks/policy-pin-allowlist.nix, while enforcement logic lives in checks/policy-pin.nix.

Usage

What this flake exports

The public contract is the outputs shape in flake.nix.

Output	Purpose
lib	Public helper scope from lib/default.nix; includes upstream nixpkgs.lib under lib.lib, source filtering helpers under lib.gitignore, and constructor helpers such as lib.mkPkgs.
overlays.default	Canonical project overlay from overlays/default.nix.
legacyPackages.${system}	Compatibility package set produced via lib.mkPkgs.
packages.${system}	Curated flat top-level installables projection from pkgs/default.nix (exportTopLevel).
templates.default	Minimal OSS starter template (alias of templates.oss).
templates.oss	Minimal OSS starter template using flake-parts and nixpkgs-matrixai.lib.mkPkgs.
nixosModules.default	Public aggregate NixOS module entrypoint.
nixosModules.procpath	Public NixOS Procpath module entrypoint.
homeModules.default	Public Home Manager module entrypoint.
checks.${system}	Local contract/policy/smoke gates consumed by nix flake check.
devShells.${system}.default	Developer shell for local repository maintenance workflows.

Current policy is explicit single-system materialization (x86_64-linux).

Start from the OSS template

Initialize a new project using the exported starter:

nix flake init -t github:MatrixAI/nixpkgs-matrixai#oss

Equivalent alias:

nix flake init -t github:MatrixAI/nixpkgs-matrixai#default

The template emits one minimal flake.nix that:

1. uses flake-parts,
2. imports nixpkgs-matrixai from GitHub,
3. constructs pkgs through nixpkgs-matrixai.lib.mkPkgs,
4. defines a small devShell consuming nixpkgs-matrixai packages.

Constructor path (lib.mkPkgs)

lib.mkPkgs is the canonical constructor for downstream composition.

Overlay ordering in lib/mkPkgs.nix is:

1. upstream nixpkgs constructor,
2. project default overlay,
3. caller-provided overlays.

Implementation shape:

mkPkgsUpstream {
  inherit system config;
  overlays = [ overlay ] ++ overlays;
}

Gitignore-aware source filtering (lib.gitignore)

This flake pins and re-exports hercules-ci/gitignore.nix under lib.gitignore.

gitignore.nix is a Nix library helper, not an installable package. Its main helpers are:

• lib.gitignore.gitignoreSource: filter a local source tree using Git ignore rules.
• lib.gitignore.gitignoreFilter: produce a composable source filter function.

Downstream flakes that already consume this repository should prefer the centralized helper unless they need independent pin control:

{ inputs, ... }:
let
  inherit (inputs.nixpkgs-matrixai.lib.gitignore) gitignoreSource;
in
{
  packages.x86_64-linux.example = pkgs.stdenv.mkDerivation {
    pname = "example";
    version = "0.1.0";
    src = gitignoreSource ./.;
  };
}

Projects should add hercules-ci/gitignore.nix as their own input only when they deliberately need a separate version or different nixpkgs follow policy.

If a wrapper producer flake such as nixpkgs-matrixai-private is the only Matrix AI input pinned by a downstream repository, that wrapper must explicitly re-export this public library surface, for example by exposing lib.gitignore from its own lib output. Flake outputs do not automatically pass through transitive input outputs.

Package registry and overlay model

pkgs/default.nix is the package registry and projection hub:

• registry.topLevel maps top-level package names to package files,
• registry.scopes maps scoped package sets (currently python3Packages),
• exportTopLevel projects flat installables to packages.${system},
• overlay wires top-level + scoped entries into overlays.default / legacyPackages.${system}.

Direct output usage

nix build 'github:MatrixAI/nixpkgs-matrixai#packages.x86_64-linux.matrixai-public-hello'
nix build 'github:MatrixAI/nixpkgs-matrixai#legacyPackages.x86_64-linux.matrixai-public-hello'

Development

Local developer shell

Enter the repository maintenance shell:

nix develop

The shell is intentionally curated for this repository's maintenance workflows and includes tools like nix, git, jq, GNU text/core utilities, curl, and wget.

Canonical local test workflow

Use these as the standard local gates:

nix flake show path:. --no-write-lock-file
nix flake check path:. --no-write-lock-file

Current checks:

• checks.${system}.contract-outputs
• checks.${system}.contract-packages
• checks.${system}.contract-modules
• checks.${system}.policy-pin
• checks.${system}.smoke-hello

Explore the pinned upstream nixpkgs in a REPL

Use this when you need to inspect the upstream nixpkgs revision that this repository currently pins.

Start a REPL from the repository root:

nix repl

Load this flake using path-source semantics:

:lf path:.

Then inspect the upstream input and its resolved source:

inputs.nixpkgs
inputs.nixpkgs.rev
inputs.nixpkgs.outPath
inputs.nixpkgs.lib.version

Instantiate the pinned upstream package set directly when you need to inspect packages as they exist before this repository's overlay and constructor logic:

pkgs = import inputs.nixpkgs { system = "x86_64-linux"; config.allowUnfree = true; }
pkgs.lib.version
pkgs.hello.version
pkgs.stdenv.hostPlatform.system

Compare that with this repository's exported package surfaces when you need to see what the public flake contract exposes after lib.mkPkgs composition:

self.legacyPackages.x86_64-linux.lib.version
self.packages.x86_64-linux.matrixai-public-hello

Use path:. for high-churn local exploration because it reads the working tree path directly. If you want parity with Git-backed flake acquisition, load the flake with :lf . instead and stage newly added files first:

:lf .

The flake.lock file remains the baseline pinned state for non-overridden inputs. Temporary --override-input usage supersedes the selected input edge in memory for that invocation only; it is not a persistent lock update.

For one-off shell checks outside the REPL, quote flake refs that contain #:

nix eval 'path:.#legacyPackages.x86_64-linux.lib.version'

Pin governance workflows

Upstream nixpkgs pin workflow

Use:

./scripts/nixpkgs-pin-policy.sh info
./scripts/nixpkgs-pin-policy.sh info --tracking-ref refs/heads/nixos-unstable
./scripts/nixpkgs-pin-policy.sh update <commit-sha>

update rewrites the managed nixpkgs block in flake.nix, refreshes flake.lock, and verifies rev consistency.

External flake pin baseline

External builtins.getFlake usage is allowlisted and enforced by checks.${system}.policy-pin.

Allowlist metadata lives in:

• checks/policy-pin-allowlist.nix

Helper scripts for maintainers

These scripts improve maintainer decision-making inside this repository. They are ergonomics helpers, not the contract authority (the contract authority remains flake outputs and checks).

1. External pin lifecycle visibility:

./scripts/external-pin-lifecycle.sh info
./scripts/external-pin-lifecycle.sh info --tracking-ref refs/heads/main

Reports include:

• allowlisted entry metadata,
• pinned commit date,
• pin age in days,
• review cadence and due state,
• tracking branch head SHA visibility.

2. Package version intelligence for policy decisions:

./scripts/package-version-intel.sh current vscodium
./scripts/package-version-intel.sh compare vscodium --candidate-ref refs/heads/nixos-unstable
./scripts/package-version-intel.sh compare matrixai-public-hello --system x86_64-linux --candidate-ref <commit-sha>

Reports include current pinned metadata and candidate metadata (version, pname, name) plus a simple changed/unchanged status.

Adding packages

1. Add or update package definitions under pkgs/top-level or pkgs/development/python-modules.
2. Register package paths in pkgs/default.nix under:
   • registry.topLevel, or
   • registry.scopes.<scopeName>.
3. Validate both surfaces:
   • packages.${system} via exportTopLevel,
   • legacyPackages.${system} via overlay composition.

Useful checks:

nix flake show path:. --no-write-lock-file
nix build '.#packages.x86_64-linux.matrixai-public-hello'
nix build '.#legacyPackages.x86_64-linux.matrixai-public-hello'

Modules

Stable exported module entrypoints are:

• nixosModules.default
• nixosModules.procpath
• homeModules.default

The public NixOS surfaces are composed from one internal registry seam:

• modules/nixos/module-list.nix is the internal list of NixOS leaf-module paths.
• modules/nixos/default.nix aggregates that list into nixosModules.default.
• modules/default.nix projects named module exports such as nixosModules.procpath from the same list.

Consumers should use the exported flake module surfaces above rather than the internal registry files directly.

Current public behavior:

• nixosModules.default aggregates the registered NixOS leaf modules.
• nixosModules.procpath provides programs.procpath.
• homeModules.default remains a placeholder until a Home Manager-specific module exists.

Example NixOS usage:

{
  imports = [
    inputs.nixpkgs-matrixai.nixosModules.procpath
  ];

  programs.procpath = {
    enable = true;
  };
}

Cross-repo consumption checks

When iterating with nixpkgs-matrixai-private, run from the private checkout:

nix flake check --override-input nixpkgs-matrixai ../nixpkgs-matrixai

For lock-based validation in private:

nix flake update nixpkgs-matrixai
nix flake check