home-lab/instruction.md

AI Agent General Instructions

Overview

This part of the document provides general instructions for tha AI agent.

General Instructions

• Treat this as iterative collaboration between user and AI agent
• Context7 MCP is mandatory for all technical documentation queries
• Use casual but knowledgeable tone - hobby/passion project, not corporate, no/little humor , be terse
• Use K.I.S.S priciples in both code and written language
• Update documentation frequently as project evolves

Language & Tool Preferences

• Functional style preferred
• Guile Scheme: System administration scripting (replace bash when possible)
• Python: AI tasks, when Python ecosystem is superior
• TypeScript/JavaScript: Web development (prefer Vite for new projects)
• Rust: Binary tools, performance-critical applications
• Bash: Only for very short scripts (< 10 lines)

Context7 MCP Usage Protocol

1. Always resolve library IDs first: Use bb7_resolve-library-id with library name
2. Get documentation: Use bb7_get-library-docs with resolved Context7-compatible ID
3. For NixOS: Search for "nixos", "nixpkgs", or specific module names
4. Required for: Any NixOS option, service configuration, package lookup, troubleshooting
5. Example workflow:

   User asks about configuring SSH -> 
   Resolve "nixos" library ID -> 
   Get docs with topic "ssh" ->
   Apply Context7 information to configuration
   

Documentation and Research Tools

• ALWAYS use Context7 MCP for NixOS: Context7 is the primary source for all NixOS information
  • Use bb7_resolve-library-id first to find the correct NixOS library ID
  • Then use bb7_get-library-docs with the resolved ID for documentation
  • Context7 provides up-to-date, authoritative NixOS documentation
  • Use it for: option names, module configurations, service setup, package names, best practices
  • Never rely on general knowledge for NixOS - always verify with Context7
• When to use Context7: Before any NixOS configuration change, package installation, service setup, or troubleshooting
• Context7 for other tools: Also use for Docker, Kubernetes, systemd, networking, and any technical documentation needs

User Configuration Strategy

• Desktop machines: Use geir user (includes desktop packages, development tools)
• Server machines: Use sma user ONLY (minimal server-focused configuration)
• Reason: The geir user module includes heavy desktop packages (browsers, GUI apps) which are inappropriate for servers
• Server examples: sleeper-service, reverse-proxy, grey-area should only import sma user module
• Desktop examples: congenital-optimist can use both geir and sma users

AI Agent Instructions: NixOS Home Lab Management

System Information

• Current: NixOS 25.05, AMD workstation, ZFS storage
• Users: geir (desktop), sma (server admin only)
• Approach: Modular NixOS + literate org-mode dotfiles (no Home Manager)
• Network: Tailscale mesh + local 10.0.0.0/24

Module Structure (Current)

Home-lab/
├── machines/{congenital-optimist,sleeper-service,grey-area,reverse-proxy}/
├── modules/{common,desktop,development,hardware,system,users,virtualization}/
├── packages/ (custom tools like 'lab' command)
└── users/geir/dotfiles/ (org-mode literate configs)

Essential Workflows

Before Any NixOS Changes

1. Use Context7: bb7_resolve-library-id nixos → bb7_get-library-docs with resolved ID
2. Stage changes in git: git add . (ensures Nix can access all files)
3. Check current state: nix flake check and verify system health
4. Test build: nix build .#nixosConfigurations.<machine>.config.system.build.toplevel

Configuration Best Practices

• Machine-specific configs: Keep in machines/<name>/ directory
• Shared modules: Only truly common settings in modules/
• User separation: geir (desktop), sma (servers only)
• Version pinning: Keep system.stateVersion = "23.11" (DO NOT CHANGE)

Deployment Workflow

• Use lab tool for all deployments and status checks:
  • lab deploy <machine> - Deploy configuration to remote machine
  • lab status - Check status of all machines in the lab
  • lab check <machine> - Verify specific machine health
  • lab test <machine> - Test configuration before deployment
• Always test locally first: nixos-rebuild test --flake .#<machine>
• Remote deployment: lab deploy <machine> handles SSH, building, and switching
• Status monitoring: Use lab status to get overview of all lab machines
• Document Context7 findings in commit messages

Git/Forgejo Configuration

• Primary repository: Hosted on self-hosted Forgejo instance
• Forgejo URL: ssh://git@git.geokkjer.eu:2222/geir/Home-lab.git
• SSH port: 2222 (proxied through reverse-proxy to grey-area:22)
• User: Must use git user for SSH compatibility
• GitHub mirror: git@github.com:geokkjer/Home-lab.git (secondary/backup)
• Remote configuration:

  git remote add origin ssh://git@git.geokkjer.eu:2222/geir/Home-lab.git
  git remote add github git@github.com:geokkjer/Home-lab.git
  

• Pushing: Primary pushes to Forgejo origin, manual sync to GitHub as needed

Key Constraints

• No Home Manager: Use org-mode literate dotfiles instead
• ZFS preservation: Never change hostId or break ZFS mounts
• Server separation: Only sma user on servers (no desktop packages)
• Context7 mandatory: All NixOS questions must use Context7 MCP

Emergency Recovery

• Previous generations available in GRUB
• ZFS snapshots: zfs rollback zpool/root@snapshot
• Keep live USB available