jpetrucciani/nix

jacobi's pinned nixpkgs setup, layered overlays, custom packages, host configs, and repo-specific tooling

Start Here

The best entry point is the curated docs hosted here! (or source found under docs/). If you are new to the repo, read these first:

1. docs/getting-started.md
2. docs/architecture.md
3. docs/home-manager.md
4. docs/tooling/index.md

If you want to make a safe change:

1. Enter the dev shell with nix develop.
2. Inspect the exposed outputs with nix flake show.
3. Pick an area:
   • hosts and machine configs: hosts/README.md
   • overlays and helpers: mods/README.md
   • package definitions: pkgs/README.md
   • scripts and automation helpers: scripts/README.md
4. Run the docs and formatting guardrails:
   • nix run .#jfmt -- --ci
   • nix run .#scripts.check_doc_links
   • nix run .#scripts.check_readme_index
5. Build the thing you touched:
   • Linux host: nix build .#nixosConfigurations.<host>.config.system.build.toplevel
   • Darwin host: nix build .#darwinConfigurations.<host>.system
   • Package: nix build .#<package-name>

Repo Map

docs/

VitePress source for the repo docs, including curated guides plus generated reference indexes.

hosts/

Concrete NixOS and nix-darwin machine definitions, shared host defaults, and reusable host modules.

mods/

The local overlay layer. This is where higher-level helper surfaces like pog, foundry, snowball, and Python overlay families are assembled.

pkgs/

Custom derivations grouped by area such as cli, cloud, server, mcp, and uv.

scripts/

Repository helpers, bootstrap scripts, and static support files. Checked script outputs also live in scripts.nix and are exposed as .#scripts.*.

secrets/

Encrypted secret material managed with agenix.

examples/

Small examples that show how to consume pieces of this repo directly.

Notable Surfaces

pog

pog is the repo's CLI-wrapper workhorse. The concrete wrapper families live under mods/pog/.

hex

hex is used here as a Nix-native spec and render workflow, especially for Kubernetes-shaped configuration.

foundry

The shared image-building surface for cloud images, installer media, and task-focused container images.

mica

A lighter package-focused environment manager that complements the broader Home Manager setup in home.nix.

hms and hmx

Convenience rebuild and switch helpers for day-to-day use on repo-managed machines.

Core Files

flake.nix

The public flake entry point. It declares inputs and exposes packages, dev shells, hosts, image builders, and helper outputs.

default.nix

Builds the shared package universe from the pinned nixpkgs input plus the local overlay stack.

overlays.nix

Orders and applies the overlays from mods/.

home.nix

The main Home Manager entry point for the daily user environment.

Useful References

awesome-nix

A curated list of the best resources in the Nix community.

nix.dev

Official documentation for getting things done with Nix. (source repo here)

keith's nix repo

Keith is a friend of mine and is the person who first introduced me to nix - his repo has been a great thing to explore to learn more about what is possible.

wuz's nix repo

wuz is a friend of mine who has some great nix modules/examples! Wuz has many examples of fully configuring things with home-manager.

how to learn nix

an awesome blog series by Ian Henry about learning nix.

nix package search

This is the official nixpkgs search engine. I use this all the time!

nix-learning

This is a collection of other resources that are useful for getting a better understanding of nix.