m3tam3re/nixos-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: complete AGENTS.md documentation

Browse Source 
- Add comprehensive project documentation to AGENTS.md
- Remove stale docs from docs/ directory
- Update agent configs (agents.nix, pi.nix)
- Update python.nix language config
- Update .gitignore
This commit is contained in:
m3tm3re
2026-04-26 14:10:54 +02:00
parent eb06533174
commit 09bc9da6d9
8 changed files with 281 additions and 1422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

485
AGENTS.md
View File

@@ -1,274 +1,299 @@
# NIXOS CONFIGURATION KNOWLEDGE BASE
# Agent Instructions
**Generated:** 2025-12-31 16:13:40 UTC
**Commit:** ebc8291
**Branch:** HEAD
This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
## OVERVIEW
Personal NixOS configuration managing 6 hosts (4 servers, 2 desktops) using flakes, agenix secrets, and feature-based home-manager setup.
## Quick Reference
## STRUCTURE
```
./
├── flake.nix # Main entry: host definitions, inputs, outputs
├── secrets.nix # Agenix public key mappings
├── hosts/
│ ├── common/ # Shared: base config, users, extraServices, ports
│ ├── m3-atlas/ # Server: 20+ containerized services with Traefik
│ ├── m3-helios/ # Server: AdGuard, internal routing
│ ├── m3-ares/ # Desktop: NVIDIA GPU, Btrfs
│ ├── m3-kratos/ # Desktop: AMD GPU, ZFS
│ └── m3-aether/ # Cloud VM
├── home/
│ ├── common/ # Home-manager base config
│ ├── features/ # Modular feature toggles (cli, desktop, coding)
│ └── m3tam3re/ # Per-host user configs
├── modules/ # Custom NixOS/home-manager modules
├── overlays/ # Package overlays (stable, locked, pinned, master)
├── pkgs/ # Custom package definitions
└── secrets/ # Agenix encrypted .age files (19 secrets)
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work atomically
bd close <id> # Complete work
bd dolt push # Push beads data to remote
```
## WHERE TO LOOK
## Non-Interactive Shell Commands
| Task | Location | Notes |
|------|----------|-------|
| Add new host | `flake.nix` + `hosts/<name>/` | Copy template from m3-atlas (server) or m3-ares (desktop) |
| Add service to m3-atlas | `hosts/m3-atlas/services/` | See containers/ for Podman + Traefik pattern |
| Configure desktop features | `home/features/desktop/` | Feature toggles with mkEnableOption |
| Add CLI tool | `home/features/cli/` | Fish + Nushell integration expected |
| Manage secrets | `secrets.nix` + `agenix -e` | SSH keys defined in secrets.nix |
| Define ports | `hosts/common/ports.nix` | Centralized port registry |
| Add user | `hosts/common/users/` | Shared across all hosts |
| Custom packages | `pkgs/default.nix` | Exposed via flake outputs |
**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
## CONVENTIONS
Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
### Secrets (agenix)
- **Create**: `agenix -e secrets/<name>.age` after adding keys to `secrets.nix`
- **Reference**: `config.age.secrets.<name>.path` in service configs
- **Pattern**: Service env files use `environmentFiles = [config.age.secrets.<service>-env.path]`
**Use these forms instead:**
### Service Organization
- **Native services**: `hosts/<host>/services/<service>.nix`
- **Containers**: `hosts/<host>/services/containers/<service>.nix`
- **Traefik integration**: All m3-atlas services include dynamic config for SSL + routing
- **Networking**: Containers use dedicated `web` network (10.89.0.0/24) with static IPs
```bash
# Force overwrite without prompting
cp -f source dest # NOT: cp source dest
mv -f source dest # NOT: mv source dest
rm -f file # NOT: rm file
### Port Management
- **Registry**: All ports defined in `hosts/common/ports.nix`
- **Access**: `config.m3ta.ports.get "service-name"`
- **Convention**: Internal services use 3000-3020 range
# For recursive operations
rm -rf directory # NOT: rm -r directory
cp -rf source dest # NOT: cp -r source dest
```
### Home-Manager Features
- **Enable**: `features.<category>.<feature>.enable = true` in user config
- **Categories**: `cli`, `desktop`, `coding`
- **Pattern**: Features are opt-in modules with default.nix aggregators
**Other commands that may prompt:**
### Multiple nixpkgs Inputs
- **stable**: 25.11 release
- **locked/pinned**: Specific commits for compatibility
- **master**: Bleeding edge
- **m3ta-nixpkgs**: Custom local overlay at `path:/home/m3tam3re/p/nix/nixpkgs`
- `scp` - use `-o BatchMode=yes` for non-interactive
- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
- `apt-get` - use `-y` flag
- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
## CODING RULES
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->
This project uses coding rules from the AGENTS repository (`inputs.agents`) plus project-specific conventions.
## Beads Issue Tracker
### Standard Rules (AGENTS repo)
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
| Rule | Source | Purpose |
|------|--------|---------|
| `languages/nix.md` | AGENTS/rules/ | Nix language conventions, flake patterns |
| `concerns/coding-style.md` | AGENTS/rules/ | General coding principles |
| `concerns/naming.md` | AGENTS/rules/ | Naming conventions per language |
| `concerns/documentation.md` | AGENTS/rules/ | Documentation standards |
| `concerns/testing.md` | AGENTS/rules/ | Testing guidelines |
| `concerns/git-workflow.md` | AGENTS/rules/ | Commit message format, branch naming |
| `concerns/project-structure.md` | AGENTS/rules/ | Project layout conventions |
### Quick Reference
### NixOS-Config Specific Rules
```bash
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
```
#### Project Structure
### Rules
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
## Session Completion
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
**MANDATORY WORKFLOW:**
1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
```bash
git pull --rebase
bd dolt push
git push
git status # MUST show "up to date with origin"
```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session
**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
<!-- END BEADS INTEGRATION -->
# Project Agent
**Workspace Path:** `/home/m3tam3re/p/NIX/nixos-config`
_(Note to Pi: Your file write/edit tools run in a different directory by default. You MUST use absolute paths starting with the Workspace Path above for ALL file operations!)_
**Generated:** 2026-04-26
---
## Stack
| Component | Version/Source |
| ---------------- | --------------------------------- |
| **Nixpkgs** | nixos-unstable + 25.05 stable |
| **Home Manager** | github:nix-community/home-manager |
| **Agenix** | github:ryantm/agenix |
| **Disko** | github:nix-community/disko |
| **NUR** | github:nix-community/NUR |
| **Formatter** | alejandra |
| **Linters** | statix, deadnix |
| **IDE** | nixd |
| **Hermes Agent** | NousResearch/hermes-agent |
| **LLM Agents** | numtide/llm-agents.nix |
---
## Structure
```
nixos-config/
├── flake.nix # Entry point
├── hosts/ # Host-specific NixOS configs
│ ├── common/ # Shared: ports, users, base config
│ ├── m3-atlas/ # Server with Traefik hub
│ ├── m3-helios/ # AdGuard DNS
│ ├── m3-ares/ # Desktop (NVIDIA)
│ └── m3-kratos/ # Desktop (AMD)
├── home/ # Home-manager configs
│ ├── common/ # Shared home config
│ ├── features/ # Feature modules (cli, desktop, coding)
│ └── m3tam3re/ # User-specific configs
├── modules/ # Custom NixOS/HM modules
├── overlays/ # Package overlays
├── pkgs/ # Custom packages
└── secrets/ # Agenix encrypted secrets
├── flake.nix # Entry point: hosts, overlays, dev shells
├── coding-rules.json # Opencode rules configuration
│
├── hosts/ # Per-host NixOS configurations
│ ├── common/ # Shared across all hosts
│ │ ├── users/ # User definitions
│ │ ├── ports.nix # Network ports config
│ │ └── extraServices/ # Common service toggles
│ ├── m3-ares/ # Main desktop
│ ├── m3-atlas/ # Desktop with disko
│ ├── m3-helios/ # Desktop with disko
│ ├── m3-hermes/ # Desktop with disko + hermes-agent
│ └── m3-kratos/ # Server with NUR
│
├── modules/ # Reusable NixOS/home-manager modules
│ ├── nixos/ # NixOS-specific modules
│ │ └── default.nix # Imports common + service configs
│ └── home-manager/ # Home-manager configurations
│
├── home/ # Per-user, per-host home configs
│ └── m3tam3re/
│ └── m3-daedalus.nix
│
├── overlays/ # Package overlays
│ ├── default.nix # Stable/locked/master branches
│ └── mods/ # Package modifications
│
├── pkgs/ # Custom packages
│
├── secrets/ # Encrypted secrets (agenix)
│ └── secrets.nix
│
├── .opencode-rules/ # Opencode AI rules
│ ├── concerns/ # Coding style rules
│ ├── languages/nix.md # Nix conventions
│ └── USAGE.md
│
└── .pi/ # Agent configuration
```
#### Naming Conventions
---
| Type | Convention | Example |
|------|------------|---------|
| Hosts | mythological-names | `m3-atlas`, `m3-helios` |
| Files | hyphen-case | `my-service.nix` |
| Variables | camelCase | `portHelpers`, `serviceConfig` |
| Options | m3ta.* | `config.m3ta.ports.get` |
| Packages | lowercase-hyphen | `hyprpaper-random` |
## Commands
#### Nix Module Pattern
| Action | Command | Notes |
| -------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- |
| **Enter dev shell** | `nix develop` | Includes alejandra, nixd, agenix, statix, deadnix |
| **Build host** | `sudo nixos-rebuild switch --flake .#m3-ares` | Replace hostname as needed |
| **Dry run build** | `sudo nixos-rebuild dry-run --flake .#m3-ares` | Validate without applying |
| **List hosts** | `nix flake show` | Shows all NixOS configurations |
| **Update flake** | `sudo nixos-rebuild switch --flake .#m3-ares --update-input nixpkgs` | Update specific input |
| **Format code** | `alejandra .` | Run before committing |
| **Check lint** | `statix check .` | Run statix for antipatterns |
| **Remove dead code** | `deadnix -w .` | Clean up unused let bindings |
| **Build ISO** | `nix build .#nixosConfigurations.m3-ares.config.system.build.isoImage` | Generate install ISO |
---
## Conventions
### Formatting & Style
- **Formatter:** `alejandra` (mandatory, run before commits)
- **Indentation:** 2 spaces (alejandra default)
- **Variables:** camelCase (e.g., `maxRetryAttempts`)
- **Types/Modules:** PascalCase (e.g., `MyService`)
- **Constants:** UPPER_SNAKE_CASE (e.g., `MAX_RETRIES`)
- **Files:** hyphen-case (e.g., `my-file.nix`)
### Nix Module Patterns
```nix
{ config, lib, pkgs, ... }:
with lib; let
cfg = config.m3ta.myModule;
in {
options.m3ta.myModule = {
enable = mkEnableOption "my module";
};
config = mkIf cfg.enable {
# Configuration here
{
options.myService.enable = lib.mkEnableOption "my service";
config = lib.mkIf config.myService.enable {
services.myService.enable = true;
};
}
```
#### Anti-Patterns (Never Do)
### Conditionals
| Don't | Do Instead |
|-------|------------|
| Hardcode ports | `config.m3ta.ports.get "service"` |
| Skip secrets.nix update | Add keys first, then `agenix -e` |
| Containers outside web network | `--network=web --ip=10.89.0.N` |
| Skip Traefik for public services | Configure dynamic config |
| Bypass extraServices flags | Use feature flags properly |
| Use `fetchTarball` | Use flake inputs |
| Use `with pkgs;` in modules | Explicit `pkgs.package` |
### Formatting & Linting
```bash
# Format (alejandra)
nix fmt
# Lint (statix, deadnix - only in dev shell)
nix develop
statix check .
deadnix .
# Validate flake
nix flake check
```
### Commit Conventions
Format: `<type>: <brief description>`
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
Examples:
- `feat: add new host m3-hermes`
- `fix: resolve port conflict in mem0 module`
- `docs: update AGENTS.md with new service`
- `style: format nix files`
- `refactor: simplify port management`
- `chore: update nixpkgs inputs`
### Tools in Dev Shell
| Tool | Purpose |
|------|---------|
| `alejandra` | Nix code formatter |
| `nixd` | Nix language server |
| `statix` | Nix linter |
| `deadnix` | Find dead code |
| `agenix` | Secret management |
## COMMANDS
```bash
# Build/deploy specific host
sudo nixos-rebuild switch --flake .#m3-ares
# Build/deploy current host
sudo nixos-rebuild switch --flake .#$(uname -n)
# Home-manager update
home-manager --flake . switch
# Update all flake inputs
nix flake update
# Add/edit secret
agenix -e secrets/<name>.age
# Infrastructure shell (OpenTofu)
nix develop .#infraShell
# Check configuration (no activation)
nixos-rebuild dry-build --flake .#<hostname>
```
## TRAEFIK PATTERNS (m3-atlas only)
### SSL Termination
- **Provider**: Godaddy DNS challenge
- **Cert storage**: `/var/lib/traefik/acme.json`
- **Config**: `hosts/m3-atlas/services/traefik.nix`
### Service Integration Template
```nix
services.traefik.dynamicConfigOptions.http = {
services.<name>.loadBalancer.servers = [{ url = "http://127.0.0.1:<port>"; }];
routers.<name> = {
rule = "Host(`<subdomain>.m3ta.dev`)";
service = "<name>";
tls.certResolver = "godaddy";
};
};
config = lib.mkMerge [
(lib.mkIf cfg.enable { ... })
(lib.mkIf cfg.extraConfig { ... })
];
```
### Container Pattern
- **Network**: `--network=web --ip=10.89.0.<sequential>`
- **Ports**: Bind localhost only (`127.0.0.1:<external>:<internal>`)
- **Database access**: `--add-host=mysql:10.89.0.1` (gateway IP)
### Anti-Patterns (AVOID)
## HOST ROLES
- **Never use `with pkgs;`** — always use explicit package references
- **Never use `builtins.fetchTarball`** — use flake inputs instead
- **Never use `import <nixpkgs>`** — always use inputs
- **Never use `builtins.getAttr/hasAttr`** — use `lib.attrByPath` or `lib.optionalAttrs`
- **Avoid anonymous functions in config** — extract to named lets
| Host | Type | Hardware | Purpose |
|------|------|----------|---------|
| m3-atlas | Server | x86_64, disko | 20+ services, Traefik hub, PostgreSQL, MySQL |
| m3-helios | Server | x86_64, disko | AdGuard DNS, internal routing |
| m3-ares | Desktop | NVIDIA, Btrfs | Personal workstation, n8n, PostgreSQL |
| m3-kratos | Desktop | AMD, ZFS | Workstation, mem0, PostgreSQL |
| m3-aether | Cloud | QEMU | General purpose VM |
| m3-daedalus | Laptop | home-only | Portable (no full NixOS config) |
### Imports
## ANTI-PATTERNS (THIS PROJECT)
- Use flake inputs for dependencies (e.g., `inputs.home-manager.nixosModules.home-manager`)
- Import relative paths with `./` or `../`
- Never use absolute paths in imports
- **DON'T** add secrets to `secrets/` without updating `secrets.nix` public keys
- **DON'T** hardcode ports - use `config.m3ta.ports.get` or add to registry
- **DON'T** create containers outside the `web` network on m3-atlas
- **DON'T** skip Traefik config for public-facing services on m3-atlas
- **DON'T** bypass extraServices flags - use `hosts/common/extraServices/` pattern
- **DON'T** commit unencrypted secrets or test with real credentials
### Secrets
## UNIQUE TO THIS CONFIG
- Secrets managed via **agenix** in `secrets/` directory
- Never commit plaintext secrets
- Use `.nix` extension for secret files
- **Custom m3ta-nixpkgs**: Local overlay for unreleased/patched packages
- **extraServices abstraction**: Boolean flags to toggle Podman, Ollama, virtualisation per host
- **Mythological naming**: All hosts named after Greek mythology
- **Dual domain strategy**: New services on `m3ta.dev`, legacy redirects from `m3tam3re.com`
- **Per-host nixpkgs versions**: Different hosts can use different nixpkgs commits via specialArgs
- **Container IP registry**: Static IP assignments in 10.89.0.0/24 subnet for predictable networking
---
## NOTES
## Key Files
- m3-atlas is the service hub - most complex configuration
- Secrets require host SSH keys defined in `secrets.nix` before `agenix -e` works
- Fish and Nushell both configured - choose per-user with shell aliases
- Color scheme (Dracula) applied via nix-colors across all visual tools
- See subdirectory AGENTS.md for deep dives on containers, desktop features, CLI tools
| File | Purpose |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
| `flake.nix` | Central entry point defining all hosts, overlays, packages, dev shells, and nixpkgs config |
| `hosts/common/default.nix` | Shared Nix settings, nixpkgs overlays, home-manager integration, user defaults |
| `hosts/m3-ares/default.nix` | Main desktop host configuration, imports common + service modules |
| `hosts/m3-ares/configuration.nix` | Desktop environment config (Hyprland, display, audio, etc.) |
| `hosts/m3-ares/programs.nix` | CLI tools, dev tools, shell configs |
| `hosts/m3-ares/services/` | Service-specific configs (firewall, printing, etc.) |
| `modules/nixos/default.nix` | Orchestrates common + configuration imports |
| `overlays/default.nix` | Package version overrides (stable/locked/master branches) |
| `.opencode-rules/languages/nix.md` | Nix-specific conventions and patterns |
---
## What to Avoid
1. **Don't modify `flake.lock`** directly — use `nix flake update`
2. **Don't use impure operations** — this is a pure flake-based config
3. **Don't commit without formatting** — always run `alejandra .` first
4. **Don't add packages to hosts directly** — prefer adding to overlays or using NUR
5. **Don't hardcode paths** — use `inputs` and relative imports
6. **Don't create monolithic modules** — keep functions under 20 lines
7. **Don't skip the dry-run** — always test with `--dry-run` before switching
8. **Don't use lib.mkDefault lightly** — understand the precedence implications
---
## Notes
### Adding a New Host
1. Add entry to `flake.nix` → `nixosConfigurations`
2. Create directory in `hosts/` with:
- `default.nix` — imports common + specific configs
- `configuration.nix` — host-specific system config
- `hardware-configuration.nix` — from `nixos-generate-config`
- `programs.nix`, `services/`, `secrets.nix` as needed
3. Run `sudo nixos-generate-config --dir ./hosts/new-host` first time
### Adding a New Package
1. For simple packages: add to appropriate overlay in `overlays/default.nix`
2. For complex packages: create in `pkgs/` directory
3. For upstream packages: use NUR or add as flake input
### Development Workflow
1. Edit config files
2. Run `alejandra .` to format
3. Run `statix check .` for linting
4. Run `sudo nixos-rebuild dry-run --flake .#m3-ares`
5. If successful: `sudo nixos-rebuild switch --flake .#m3-ares`
### Remote Building
```bash
# Build on remote machine
nix copy --to ssh://user@host .#nixosConfigurations.m3-ares.config.system.build.toplevel
ssh user@host 'sudo nixos-rebuild switch --flake /nix/store/...-closure'
```
### Home Manager
- Home configs live in `home/m3tam3re/`
- Use `home-manager.users.m3tam3re` in host config
- Access via `config.home-manager.users.m3tam3re`