Ecosystem map

Updated

July 30, 2026

Ecosystem map

Goal: Map the adjacent tooling landscape, try exactly one of devenv / Snowfall / nix-darwin in a disposable trial, and write a keep/drop decision against your flake layout—without rewriting Capstone mid-flight.

Note

Syllabus rule: try one, don’t collect all. Tool tourism is how deep curricula die mid-book.

Why this chapter exists

By now your layout is intentional: flake hosts, modules, HM, deploy, tests. The ecosystem constantly offers frameworks that promise less boilerplate. Some are worth it; many are expensive rewrites. Experts sample with a comparison table, not a weekend migration of Capstone main.

Theory 1 — Layers of “ecosystem”

Layer	Examples	Problem they target
Devshell UX	devenv, devbox, `nix develop`, direnv	Fast project environments
Flake structure frameworks	flake-parts, Snowfall, digga (legacy)	Scale modules/systems/homes
Darwin / non-NixOS	nix-darwin, HM standalone	Same declarative story on macOS
Deploy	deploy-rs, Colmena, nixinate	Ops & fleet part
Secrets	sops-nix, agenix	Services & security part
Caches	Cachix, Attic, Harmonia	Packaging / ops
Install / metal	nixos-anywhere, disko, images	Ops & fleet
UX wrappers	nh, nixos-rebuild-ng experiments	Faster day-2 commands
Editors / templates	templates repos, blueprint flakes	Speed of scaffolding

Today’s forced choice is among devenv, Snowfall, nix-darwin—three different layers. Pick the one that matches your pain:

If your pain is…	Prefer trying
Polyglot project shells, services in dev	devenv
Many hosts/homes, naming convention fatigue	Snowfall (or double-down on flake-parts you may already use)
You live on macOS half the time	nix-darwin
None of the above	Still pick one; learn by contrast

Theory 2 — devenv (project environments)

What it is: A Nix-powered dev environment tool (CLI + modules) focused on languages, processes, pre-commit, and local services—closer to “compose for dev” than to NixOS hosts.

Typical win: New contributors run one tool and get DB + language toolchain.

Typical cost: Another module system dialect; CI must speak devenv; overlap with devShells you already have.

# illustrative — follow current devenv docs for install
# nix profile install nixpkgs#devenv
# devenv init
# devenv shell

Compare to house default

Concern	`nix develop` + direnv	devenv
Mental model	Flake `devShells`	devenv modules + CLI
Services (postgres…)	Manual / process-compose DIY	First-class modules often
Capstone impact	Low if already working	Medium if dual standards

Theory 3 — Snowfall (flake library / structure)

What it is: A convention-heavy library for laying out flakes: systems, modules, packages, homes under standard paths, auto-discovery.

Typical win: Multi-host monorepos with consistent naming and less flake.nix glue.

Typical cost: Framework lock-in; debugging indirection; migration of a working hand layout.

Compare to flake-parts

Concern	Hand layout / flake-parts	Snowfall
Structure	Explicit imports	Convention + library
Learning	Your code is visible	Magic paths
Capstone rewrite cost	Low if already structured	Often high mid-flight

Snowfall and flake-parts both attack “structure,” differently. Trying Snowfall does not require abandoning flake-parts forever—decision is local.

Theory 4 — nix-darwin

What it is: Nix modules for macOS system configuration—spiritual cousin of NixOS modules, not a Linux VM.

Typical win: One repo language for laptop (Darwin) + servers (NixOS) + Home Manager.

Typical cost: Darwin modules ≠ NixOS modules; GUI/casks world; CI harder; not a substitute for your lab VM.

# only on a Mac you own — follow current nix-darwin + flakes docs
# darwin-rebuild switch --flake .#hostname

If you have no Mac, you may still read a nix-darwin sample config and write a comparison—or pick devenv/Snowfall for a hands-on trial instead.

Shared idea	Divergence
Module options, activation	Different option trees
HM integration common	GUI apps / Homebrew friction
Flakes	Same pin discipline

Theory 5 — Decision framework (keep/drop)

Score 1–5 for your context:

Criterion	Weight idea
Reduces your real weekly pain	High
Clear primary docs	High
Plays with flakes + lock discipline	High
Compatible with sops/deploy/tests	High
Rewrite cost of Capstone	Critical penalty
Bus factor / maintenance	Medium
Fashion / social media mindshare	Zero

Default Capstone policy: adopt only if score says “yes” and migration is a branch, not a rewrite of main before disaster recovery proof.

decision ∈ { keep-current, adopt-later, trial-only-drop }

Theory 6 — Ecosystem postcard (vocabulary)

You need names for comparative conversations even without installs:

Name	One-line purpose
flake-parts	Modular flake output composition
nixos-anywhere	Remote install from existing SSH
nh	Friendlier rebuild/search UX
Attic	Self-hosted binary cache
digga	Legacy flake framework (historical literacy)
blueprint / templates	Scaffold speed
nixos-generators	Image formats from NixOS configs
Lanzaboote	Secure Boot UKI/signing path

≤15 lines total in notes is enough—depth belongs to the one trial.

Theory 7 — Integration risks matrix

Trial tool	Risk to secrets	Risk to deploy	Risk to tests
devenv	Low	Low	Low (CI may need devenv)
Snowfall	Medium (path moves)	Medium	Medium (check wiring)
nix-darwin	Low on Linux lab	N/A for NixOS hosts	Separate CI

Never “finish” a trial by force-pushing Capstone restructure without a branch review.

Worked example — COMPARE.md skeleton

# COMPARE.md — devenv vs house layout (example)

## Context
- Capstone flake with nixosConfigurations.lab, sops-nix, deploy-rs
- Pain: polyglot shells inconsistent across repos

## Scores (1–5)

| Criterion | House | devenv | Weight |
|-----------|-------|--------|--------|
| Weekly pain relief | 2 | 4 | 5 |
| Docs clarity | 4 | 4 | 4 |
| Flake/lock fit | 5 | 4 | 5 |
| sops/deploy/tests | 5 | 3 | 5 |
| Capstone rewrite cost | 5 | 2 | 5 |

## Decision
We will **not** adopt before Capstone freeze because rewrite cost outweighs shell pain;
revisit after Capstone freeze if side projects still hurt.

## Evidence from trial/
- commands run:
- what broke:
- time spent:

Lab 0 — Workspace

mkdir -p ~/lab/nixos/internals/ecosystem/trial
cd ~/lab/nixos/internals/ecosystem

Do not trial on the only copy of Capstone; branch or separate directory.

Lab 1 — Map your current layout (30 min)

In LAYOUT.md:

flake.nix outputs:
  nixosConfigurations: …
  homeConfigurations / HM-as-module: …
  devShells: …
  checks: …
  packages: …
  deploy / colmena: …
modules/: …
hosts/: …
secrets/: …

List top 3 pains (e.g. “shells inconsistent”, “host boilerplate”, “no Mac story”).

Lab 2 — Pick one tool and trial

If devenv

devenv init in trial/app or import docs’ minimal flake.
Add one language toolchain you actually use.
Optional: one service (postgres/redis) if docs make it easy.
Enter shell; run a real command (tests/build).
Note direnv integration if any.
Time spent + friction log.

If Snowfall

Scaffold a tiny Snowfall flake (one system stub, one module).
Do not migrate all hosts.
Trace: where does a host definition live? How is it discovered?
Compare to your hosts/lab/default.nix pattern.
Eval something small; capture errors as learning.

If nix-darwin

On Mac: flake with one darwinConfigurations; apply to a throwaway aspect if possible.
Or read-only deep dive: clone an example, map options vs NixOS cousins.
Document what cannot be shared as-is with NixOS modules.

Timebox: 2–4 hours max for trial hands-on.

Lab 3 — Comparison table (required)

Complete COMPARE.md per Theory 5–worked example. Include explicit paragraph:

“We will / will not adopt before Capstone freeze because…”

Lab 4 — Ecosystem postcard

In ≤15 lines, define in your words: flake-parts, nixos-anywhere, nh, Attic. No install required.

Lab 5 — Capstone protection check

# Capstone main should be untouched by trial frameworks
cd /path/to/capstone-flake
git status
git log --oneline -5

If you “accidentally” started migrating main, revert or move work to a branch named experiment/… and restore main to last known good.

Acceptance: git status clean on Capstone main regarding trial frameworks; trial lives under trial/ or experiment/* branch.

Lab 6 — Teach-back (5 bullets)

Explain to a peer:

What pain you tried to solve
What you tried
Score highlight
Decision
Revisit criteria

Common gotchas

Mistake	What to do
Trying all three “a little”	Violates the chapter; pick one
Rewriting Capstone main branch	Use `trial/` only
Adopting for aesthetics	Score against pain list
devenv and heavy custom shells forever duplicated	Choose a house standard
Assuming Snowfall ≈ NixOS	It’s flake structure, not an OS
nix-darwin as lab substitute	Still need Linux NixOS for Capstone
Infinite template shopping	Timebox trial to hours, not days

Checkpoint

LAYOUT.md + top pains
One tool trial notes or read-only darwin depth
COMPARE.md with keep/drop decision
Ecosystem postcard vocabulary
Capstone main layout untouched (or only trivial fixes)
Three personal gotchas

Commit

git add .
git commit -m "lab(nixos): ecosystem trial and keep/drop decision"

Write three personal gotchas before continuing.

→ Comparative landscape — steelman alternatives to NixOS.

Ecosystem map

Why this chapter exists

Theory 1 — Layers of “ecosystem”

Theory 2 — devenv (project environments)

Compare to house default

Theory 3 — Snowfall (flake library / structure)

Compare to flake-parts

Theory 4 — nix-darwin

Theory 5 — Decision framework (keep/drop)

Theory 6 — Ecosystem postcard (vocabulary)

Theory 7 — Integration risks matrix

Worked example — COMPARE.md skeleton

Lab 0 — Workspace

Lab 1 — Map your current layout (30 min)

Lab 2 — Pick one tool and trial

If devenv

If Snowfall

If nix-darwin

Lab 3 — Comparison table (required)

Lab 4 — Ecosystem postcard

Lab 5 — Capstone protection check

Lab 6 — Teach-back (5 bullets)

Common gotchas

Checkpoint

Commit

Next