main

Project

This is my homelab git repository. It is a comprehensive NixOS and home-manager monorepo for managing personal infrastructure, system configurations, and custom tools. It also has more “dynamic” configuration files in the dots folder.

Building

  • Building host nixos configurations

    • Use make build for testing the current host configuration (nixos).
    • Use make host/<hostname>/build for testing a given host configuration.
    • To test a host configuration without building, it’s make dry-build or make host/<hostname>/dry-build.
    • To deploy a host live, it’s make switch or make host/<hostname>/switch.
    • To deploy a host on next boot, it’s make boot or make host/<hostname>/boot.
    • You can get the list of hosts from the flake.nix configuration.

  • To build keyboards, there is a keyboards/Makefile for the targets.

  • In general, running make help will tell you what you can run/build.

  • Don’t ever do commit unless you are being explicitely asked for it.

  • If you get asked to commit then use this rules:

    • Follow Conventional Commits 1.0.0.
    • 50 chars for title 70 chars for body.
    • Cohesive long phrase or paragraph unless multiple points are needed.
    • Use bullet points only if necessary for clarity.
    • Past tense.
    • State what and why only (no “how”).

  • IMPORTANT: Never use home-manager switch or nixos-rebuild commands directly. Always use make switch or the appropriate make targets.

Architecture

Nix structure

The repository follows a modular architecture centered around flake.nix:

  • globals.nix: Global configuration including machine definitions (network, SSH, syncthing), DNS zones, and VPN settings
  • /systems: NixOS system configurations, organized by hostname with a shared /systems/common directory containing base, desktop, hardware, programs, services, and users modules
  • /home: Home-manager configurations with /home/common containing desktop, dev, services, and shell modules. Usually it gets build as part of systems.
  • /pkgs: Custom Nix packages that are exposed via overlays
  • /tools: Source code for custom tools (battery-monitor, emacs configuration)
  • /modules: Custom NixOS modules (wireguard-client, wireguard-server, govanityurl, gosmee)
  • /overlays: Nix overlays for additions, modifications, and unstable packages

Host Configuration Pattern

Each host has a dedicated directory in /systems/<hostname> containing:

  • boot.nix: Boot configuration (bootloader, initrd, kernel modules)
  • hardware.nix: Hardware-specific settings (hardware imports, filesystem mounts)
  • extra.nix (optional): Additional host-specific configuration
  • home.nix (optional): Host-specific home-manager configuration

Package Management

Custom packages are defined in /pkgs/default.nix and exposed through the additions overlay. They are built using standard Nix packaging functions (pkgs.callPackage). The repository provides packages for both x86_64-linux and aarch64-linux architectures.

Secrets Management

Secrets are managed using agenix:

  • secrets.nix defines which secrets are encrypted for which hosts and users
  • Yubikeys are used for age encryption
  • Host SSH keys are used for system-level secret decryption

Key Patterns

Adding a New Package

  1. Create package directory in /pkgs/<package-name> with default.nix
  2. Add entry to /pkgs/default.nix using pkgs.callPackage
  3. Package will be available via nix build .#<package-name>

Keyboard Firmware

Deployment Safety

IMPORTANT: Always ask for user confirmation before deploying to remote hosts.

When making configuration changes that require deployment:

  1. Show the changes first - Use git diff or explain what will be deployed
  2. Ask for explicit approval - Never run nixos-rebuild switch or make host/<hostname>/switch without asking the user first
  3. Suggest dry-run builds - Offer to run make host/<hostname>/build or nixos-rebuild build to test first
  4. Confirm the target host - Make sure the user wants to deploy to that specific machine

Examples of what to ask:

  • “Would you like me to deploy these changes to rhea?”
  • “Should I run a dry-build first to verify the configuration?”
  • “These changes will affect . Do you want to proceed with the deployment?”

Never deploy automatically - even if it seems like the logical next step. Remote deployments can have significant impact on running services.

Code Analysis Tools

ast-grep

AST-based structural search for code patterns. Fast, accurate, works across Nix/Bash/Go/Python/YAML/JSON.

Usage: Run from repo root (~/src/home). Use ast-grep scan or see docs/code-analysis/ast-grep-guide.md for details. Pre-configured rules in .ast-grep/.

File Management Guidelines

Org Files

  • NEVER edit .org files directly with Write, Edit, sed, or any text manipulation tool
  • ALWAYS use emacsclient or the org_todo tool to modify org files
  • This applies to ~/desktop/org/todos.org, notes, journal, and all .org files
  • Path validation hooks will block direct writes to .org files in ~/desktop/org/

Temporary Files

  • Always write temporary scripts to /tmp/ instead of the home directory (~/)
  • Use descriptive names with appropriate extensions (e.g., /tmp/fix-session-filenames.sh)
  • Clean up temporary files after use with rm command