Nixflakes

Centralized Nix configuration for personal machines, services, and custom packages.

This repository keeps the host-specific pieces small by splitting reusable module logic, package definitions, and shared configuration into clear layers. It also packages a jailed mitchpi and a nixvim-based mitchvim.

Repository layout

The repo is organized into a few stable layers:

• config/ — concrete configuration consumed by NixOS, Home Manager, Neovim, pi-agent, and shell tooling
• modules/ — reusable NixOS and Home Manager modules that define option interfaces and heavier logic
• pkgs/ — custom derivations and package definitions extending nixpkgs
• platforms/ — per-machine hardware, boot, and filesystem configuration (<hostname>.nix)
• lib/ — shared helper libraries, including jail helpers and pi-agent support code
• overlay.nix — overlay for upstream bug fixes and package adjustments

mitchpi runs inside a read-only jail that forwards API keys while limiting writable state under ~/.pi/.

Each NixOS machine imports config/nixos/, modules/nixos/, and its matching platforms/<name>.nix. Home Manager follows the same split between shared configuration and reusable modules.

Directory	Purpose
config/nixos/	Shared NixOS configuration: core system, networking, and services
config/home-manager/	Shared Home Manager configuration: core, graphical, terminal, services, and theme
config/nixvim/	Neovim configuration consumed by mitchvim
config/pi-agent/	Shared pi-agent profile, resources, and jail runtime inputs
config/starship/	Shell prompt theme
modules/	Reusable NixOS and Home Manager module definitions
platforms/	Per-machine boot, filesystem, and hardware configuration
lib/jail/	Read-only sandbox combinators
lib/pi-agent/	Inventory ingestion and jail profile construction
pkgs/	Custom derivations written in a nixpkgs-friendly style
overlay.nix	Overlay for upstream bug-fix patches with nixpkgs issue references

Machines

Physical

Machine	Platform	Notes
surface	platforms/surface.nix	Daily-driver Surface Pro with GNOME, secure boot, and Skylake tuning

Virtual

Machine	Platform	Notes
lxc	platforms/lxc.nix	Proxmox LXC without a GUI
wsl	platforms/wsl.nix	WSL2 environment

Homelab containers

Deployed with deploy-rs to *.home.pleunetowne.com.

Machine	Role
git, git-runner1	Git server and CI runner
immich	Photo management
jellyfin	Media server
jump	Bastion host
llm	LLM inference
nas	NAS with Alder Lake tuning
nextcloud	Cloud sync with rollback disabled
notes	Notes server
paperless	Document management

Bootstrapping a new machine

1. Build the custom ISO (uncomment live-iso in flake.nix first):

   nix build .#nixosConfigurations.live.config.system.build.isoImage
   # Write the resulting image to USB, then boot the target machine.
   

2. Partition disks and run nixos-generate-config --root /mnt. The exact partitioning scheme depends on the machine.

3. Create platforms/<hostname>.nix by extracting the generated filesystem mounts, boot configuration, and kernel modules into a new platform file. Follow the structure used by existing platform files.

4. Add the machine to flake.nix:

   • add it to nixosConfigurations with makeSystem
   • if it is a homelab host, add it to deploy.nodes with its FQDN

5. Install:

   nixos-install --flake /path/to/repo#<hostname>
   reboot
   

6. Run the first full rebuild after the new system boots:

   nixos-rebuild switch --flake .#<hostname>
   

Key packages

mitchpi

A jail-sandboxed pi-agent, built from pkgs.pi-agent and composed with config/pi-agent/profile.nix.

• Resources — bundles pi-ask, pi-hermes-memory, pi-subagents, rpiv-btw, rpiv-todo, pi-token-burden, plus local skills, extensions, prompts, and themes from config/pi-agent/resources/
• API keys — forwarded from the host environment (OpenAI, Anthropic, Google, Mistral, DeepSeek, xAI)
• State — persisted through selective mutable mounts under ~/.pi/agent/ for auth, memory, sessions, and models
• Network — shared namespace
• Filesystem — everything else remains read-only

mitchvim

Neovim built with nixvim from config/nixvim/options.nix.

Running mitchpi and mitchvim

Both commands rely on the substituter at https://nix.pleunetowne.com for practical local and remote use.

# From a local checkout
nix run .#mitchpi --option substituters "https://nix.pleunetowne.com/?trusted=1"
nix run .#mitchvim --option substituters "https://nix.pleunetowne.com/?trusted=1"

# Directly from git (no clone required)
nix run git+https://git.pleunetowne.com/mitchpleune/nixflakes.git#mitchpi --option substituters "https://nix.pleunetowne.com/?trusted=1"
nix run git+https://git.pleunetowne.com/mitchpleune/nixflakes.git#mitchvim --option substituters "https://nix.pleunetowne.com/?trusted=1"

Security

• Secrets — agenix manages encrypted secrets stored in a private repo: git+ssh://git@git.pleunetowne.com:2223/mitchpleune/secrets.git

  cd $(nix build --no-link --print-out-paths .#nixosConfigurations.surface.config.age.secrets.wireguard-template.file 2>/dev/null || echo '.')
  agenix -e secret.age    # create or edit a secret
  agenix -d secret.age    # decrypt a secret
  

• Secure boot — lanzaboote is enabled on surface

Update scripts

Many custom packages ship an update.sh helper for refreshing pinned sources. Notable examples include pi-agent, pi-ask, pi-hermes-memory, pi-subagents, pi-quotas, pi-token-burden, code-review-graph, and the rpiv-mono family.

Operations

Validate quickly (no build)

# Check syntax and dependency resolution across the whole flake
nix flake check --no-build

# Fast eval to confirm a package or config evaluates
nix eval --option eval-cache false .#packages.x86_64-linux.mitchpi.drvPath
nix eval --option eval-cache false .#packages.x86_64-linux.mitchvim.drvPath
nix eval --option eval-cache false '.#homeConfigurations."mitch@surface".activationPackage.drvPath'

Build

nix build --option eval-cache false --no-link .#packages.x86_64-linux.mitchpi
nix build --option eval-cache false --no-link .#packages.x86_64-linux.mitchvim
nix build --option eval-cache false --no-link '.#homeConfigurations."mitch@surface".activationPackage'

Rebuild

# Apply NixOS + Home Manager changes to surface
nixos-rebuild switch --flake .#surface

# Test a configuration in a VM before deploying
nixos-rebuild build-vm --flake .#surface

Apply Home Manager only

Faster iteration for dotfiles, editor config, and other user-level changes by applying just the Home Manager layer from the NixOS configuration:

home-manager switch --flake .#nixosConfigurations.surface.config.home-manager.users.mitch.home

Smoke test

out=$(nix build --option eval-cache false --no-link --print-out-paths .#packages.x86_64-linux.mitchpi)
"$out/bin/pi" -p "hello" </dev/null

Deploy homelab hosts

nix develop   # provides deploy-rs and agenix-cli

deploy .#git
deploy .#nas
deploy --targets .#git .#git-runner1

Format

nix fmt

Gotchas

• New files must be git added before flakes can see them. If Nix complains that a path is untracked, add it and rerun.
• Use --option eval-cache false while debugging to force re-evaluation and avoid stale cache results.
• Always pass --no-build to nix flake check to avoid accidentally building every NixOS configuration.

Troubleshooting

# Clear and rebuild font caches after system updates
rm -r ~/.cache/fontconfig
fc-cache -vr