current build

This commit is contained in:
ari committed 2026-06-21 00:11:14 -04:00
1 parent 842ac07091
commit c031fc7ae1
11 files changed
+401 -1

No files matched your search

+141
View File
@@ -0,0 +1,141 @@
# Agent Guidelines — nixos-setup
Rules and best practices for any AI agent working in this repository.
Read this file before making any changes.
---
## Hard Rules — Never Break These
### ❌ NEVER run builds or system switches
Do NOT run any of the following, ever:
```
nixos-rebuild switch / test / build
nh os switch / test / build
skyg os switch / test / build
skyg remote switch / test / build
skyg hm switch / build
nix build
nix flake check
```
These commands take 20–40+ minutes, consume significant CPU/RAM, and can break a live
system. The user runs these themselves after reviewing changes. Your job is to make
correct edits to the source files — not to apply them.
### ❌ NEVER edit `flake.lock` by hand
This file is managed exclusively by `nix flake update`. Editing it manually will corrupt
the lock file and break all builds.
### ❌ NEVER edit `*.hardware-configuration.nix` files
These are generated by `nixos-generate-config` and reflect the physical hardware. Edits
will be overwritten on the next hardware scan and can render a system unbootable.
### ❌ NEVER touch secrets
Do not read, write, or delete files in `secrets/`. Encrypted `.age` files must only be
managed with `agenix` via the `skyg secrets` commands. Do not modify `secrets.nix` unless
the user explicitly asks and explains the full context.
### ❌ NEVER add `imports = [...]` to host files
Host files (`hosts/<hostname>.nix`) do not use `imports`. All modules are composed through
the `makeNixOs` call in `flake.nix` via `modules/main.nix`. Adding imports to a host file
breaks the composition model.
---
## Safe Operations
These are always safe to perform without asking:
- Reading any `.nix`, `.md`, or config file
- Editing host files (`hosts/<hostname>.nix`) to add/remove packages or options
- Editing module files in `modules/`
- Creating or updating documentation in `docs/` or `ABOUTME.md` / `GUIDELINES.md`
- Adding new packages to `pkgs/`
- Editing configs in `configs/`
---
## NixOS Conventions in This Repo
### Option Namespace
All custom options live under `skyg.*`. Never introduce options under any other top-level
namespace. Check `modules/lib.nix` for the full `skyg.*` structure.
```nix
# Correct
skyg.nixos.desktop.enable = true;
skyg.nixos.server.services.comfyui.enable = true;
# Wrong — do not invent new top-level attrs
myOptions.desktop.enable = true;
```
### Enable/Disable Pattern
All modules follow `lib.mkIf cfg.enable { ... }`. Always gate config behind an `enable`
option. Default should be `false` unless the feature is universally required.
### Host Files vs Shared Modules
- **Host-specific** (one machine only): goes in `hosts/<hostname>.nix`
- **Shared** (multiple hosts): goes in the appropriate `modules/nixos/` or `modules/core/` submodule
- When in doubt, keep it in the host file and extract later if reuse emerges
### Package Placement
- Packages needed on all desktops → `modules/nixos/desktop/packages.nix`
- Packages for one host only → `environment.systemPackages` in the host file
- Custom/third-party packages not in nixpkgs → `pkgs/<name>/default.nix` with an overlay in `modules/core/default.nix`
### Home Manager
Home Manager config lives inside `home-manager.users.<name>` blocks. Do not mix
system-level and HM-level options. The HM entry point is `modules/home/default.nix`.
### Greeter
Both desktop hosts (`fwbook`, `hl-fwdesk`) use DankMaterialShell greeter via:
```nix
programs.dank-material-shell.greeter = {
enable = true;
compositor.name = "niri";
configHome = "/home/<username>";
};
```
Do not configure `services.greetd` manually on these hosts — the DMS module handles it.
---
## Navigation Tips
| Question | Where to look |
|---|---|
| What hosts exist? | `hosts/` + `docs/hosts/README.md` |
| What does a `skyg.*` option do? | `modules/` — find the defining `.nix` file |
| What flake inputs are available? | Top of `flake.nix` |
| What binary caches are configured? | `modules/core/nix-substituters.nix` |
| What secrets exist? | `secrets.nix` (lists files + authorized keys) |
| What custom packages exist? | `pkgs/` |
| Full API reference | `docs/modules/README.md` |
| Host details (ports, services, hardware) | `docs/hosts/README.md` |
---
## Validation Without Building
After making changes you can verify syntax without running a build:
```bash
# Check Nix expression syntax only (fast, safe)
nix-instantiate --parse <file>.nix
# Check the flake structure without building
nix flake show --no-build 2>/dev/null
```
Even these are optional — the user will validate by running `nh os switch` themselves.
---
## Commit / Branch Policy
- Do NOT commit changes or create branches unless the user explicitly asks
- Do NOT `git add`, `git commit`, or `git push` autonomously
- Describe what you changed in your final message so the user can review before committing
+15
View File
@@ -0,0 +1,15 @@
# apps/
Standalone application binaries and AppImages that are not managed through Nix packages.
## Contents
| File | Description |
|---|---|
| `tabby-1.0.205-linux-arm64.AppImage` | Tabby AI coding assistant — ARM64 AppImage for manual deployment |
## Notes
- Files here are **not** referenced by the flake directly
- AppImages in this folder are deployed or run manually as needed
- Do not add packages here that can be expressed as proper Nix derivations — use `pkgs/` instead
+31
View File
@@ -0,0 +1,31 @@
# bin/
The `skyg` CLI — the single entry point for all system management tasks in this repo.
## Structure
```
bin/
├── skyg # Bash shim: exec nu --commands "use lib/cmds.nu *; skyg $*"
└── lib/
├── cmds.nu # All subcommand implementations (NuShell — source of truth)
├── profile.nu # Profile helpers and tab-completion data
└── types.nu # Type definitions
```
## Key Commands
| Command | Description |
|---|---|
| `skyg os switch` | Rebuild and switch local system |
| `skyg remote switch <host>` | Deploy to a remote host |
| `skyg hm switch` | Apply Home Manager config |
| `skyg update [input]` | Update flake inputs |
| `skyg build-iso` | Build bootable ISO |
| `skyg openwrt` | Deploy OpenWrt config |
| `skyg rollback` | Roll back to previous generation |
## Agent Note
> **Never invoke `skyg` commands that trigger builds or switches.**
> Only the user runs these. Edits to `cmds.nu` are safe if the user asks for CLI changes.
+22
View File
@@ -0,0 +1,22 @@
# configs/
Application configuration files that are symlinked into `~/.config/` via
`system.userActivationScripts` (using `skygUtils.makeHyperlinkScriptToConfigs`
from `modules/skyg-utils.nix`).
## Contents
| Path | Description |
|---|---|
| `niri/` | Niri Wayland compositor config |
| `hypr/` | Hyprland compositor config |
| `hyprpanel/` | HyprPanel bar/widget config |
| `extra.nu` | Extra NuShell config sourced at shell startup |
| `fwbook.knsv` | fwbook-specific Kanshi display profile |
| `libinput-gestures.conf` | Touchpad gesture bindings |
## Notes
- Changes here take effect on next login or when the activation script runs
- These are **not** NixOS options — they are plain config files managed as repo content
- The symlink mechanism is defined in `modules/skyg-utils.nix`
+36
View File
@@ -0,0 +1,36 @@
# hosts/
One NixOS configuration file per managed machine, plus hardware configs and host-specific scripts.
## Structure
```
hosts/
├── <hostname>.nix # Host configuration (packages, services, options)
├── <hostname>.hardware-configuration.nix # Generated by nixos-generate-config — DO NOT EDIT
├── scripts/
│ └── fwbook/ # fwbook-specific shell scripts
│ └── functions.sh # ZSH functions sourced at shell startup
```
## Managed Hosts
| File | Host | Role |
|---|---|---|
| `fwbook.nix` | fwbook | Framework 13 AMD — personal laptop / daily driver |
| `hl-fwdesk.nix` | hl-fwdesk | Framework Desktop AI Max 300 — AI workstation |
| `hl-fws1.nix` | hl-fws1 | Framework 11th Intel — K3s server node |
| `hl-bigbox1.nix` | hl-bigbox1 | AI/compute server (NVIDIA + AMD) |
| `hl-bigbox2.nix` | hl-bigbox2 | NFS storage server |
| `hl-minipc1.nix` | hl-minipc1 | Core infra: Gitea, nix-serve, Docker registry |
| `hl-minipc2.nix` | hl-minipc2 | Container/media server |
| `hl-minipc3.nix` | hl-minipc3 | K3s worker node |
| `hl-terra1.nix` | hl-terra1 | NFS storage + Jellyfin backup |
| `iso.nix` | iso | Bootable NixOS installer image |
## Rules
- **Do not add `imports = [...]`** to host files — module composition happens in `flake.nix` via `modules/main.nix`
- **Do not edit `*.hardware-configuration.nix`** — these are generated and will be overwritten
- Host-specific packages and one-off settings belong here; anything reused across hosts belongs in `modules/`
- See `docs/hosts/README.md` for full per-host service/port/package reference
+1 -1
View File
@@ -1,4 +1,5 @@
{ pkgs { pkgs
, lib
, ... , ...
}: }:
let let
@@ -154,7 +155,6 @@ in
OLLAMA_KEEP_ALIVE = "24h"; OLLAMA_KEEP_ALIVE = "24h";
}; };
}; };
hardware.graphics.enable = true;
hardware.enableAllFirmware = true; hardware.enableAllFirmware = true;
hardware.amdgpu = { hardware.amdgpu = {
opencl.enable = true; opencl.enable = true;
+42
View File
@@ -0,0 +1,42 @@
# modules/
All reusable NixOS and Home Manager modules. Every host gets the full module tree via
`modules/main.nix`, which is wired up in `flake.nix` through the `makeNixOs` helper.
## Structure
```
modules/
├── lib.nix # makeNixOs / makeIso / makeHomeManagerUsers / makeDarwinModule / eachSystem
├── main.nix # Base module imported by every host: core/ + nixos/ + network-drives.nix
├── skyg-utils.nix # makeHyperlinkScriptToConfigs (symlinks configs/ → ~/.config/)
├── macos.nix # macOS / nix-darwin module
├── network-drives.nix # skyg.networkDrives — NFS automount options
├── core/ # User, binary caches, distributed builds, macOS workarounds
├── home/ # Home Manager: shell, programs, git, fonts, services
├── nixos/
│ ├── common/ # Core system settings, networking, SSH, QEMU, fonts, hardware
│ ├── server/ # Server services: K3s, Gitea, AI stack, DNS, Dockge, ARRs...
│ └── desktop/ # Desktop: tiler (niri/hyprland), packages, theming, crypto
└── openwrt/ # OpenWrt router config generator
```
## Option Namespace
All custom options live under `skyg.*`. Never introduce options outside this namespace.
```
skyg.user.* → core/user.nix
skyg.networkDrives.* → network-drives.nix
skyg.nixos.common.* → nixos/common/
skyg.nixos.desktop.* → nixos/desktop/
skyg.nixos.server.* → nixos/server/
skyg.core.* → core/
```
## Key Conventions
- All modules gate config with `lib.mkIf cfg.enable { ... }`
- Default for every `enable` option is `false` unless universally required
- New modules go in the most specific subdirectory that matches their scope
- See `docs/modules/README.md` for full option reference and architecture diagram
+33
View File
@@ -0,0 +1,33 @@
# openwrt-routers/
Declarative OpenWrt router configurations, compiled to UCI (Unified Configuration Interface)
by the Rust-based generator in `modules/openwrt/generator/`.
## Contents
| File | Description |
|---|---|
| `glmain.nix` | Configuration for the `glmain` GL.iNet router (gateway at `10.0.0.1`) |
## How It Works
1. `glmain.nix` declares the router's network topology, firewall zones, DHCP, and DNS in Nix
2. `modules/openwrt/default.nix` passes it through the generator binary
3. `skyg openwrt` SSHes to the router and applies the generated UCI config
## Deploying
```bash
skyg openwrt
```
## Adding a New Router
1. Create `openwrt-routers/<name>.nix` modelled on `glmain.nix`
2. Add a `openwrt-<name>` package output in `flake.nix` using the `openwrt` helper
3. Add a deploy target in `bin/lib/cmds.nu`
## Notes
- Router credentials are stored in `secrets/glmain.json.age`
- Do not hardcode passwords or PSKs in the `.nix` file — use agenix secrets
+28
View File
@@ -0,0 +1,28 @@
# pkgs/
Custom Nix package derivations for software not available in nixpkgs (or needing local overrides).
Packages here are exposed via an overlay defined in `modules/core/default.nix`.
## Contents
| Package | Description |
|---|---|
| `grok-cli/` | xAI Grok CLI — prebuilt static binary, fetched per-platform. Exposed as `pkgs.grok-cli`. |
## Adding a New Package
1. Create `pkgs/<name>/default.nix` with a standard derivation
2. Add an entry to the overlay in `modules/core/default.nix`:
```nix
(final: _prev: {
<name> = final.callPackage ../../pkgs/<name> { };
})
```
3. Reference it as `pkgs.<name>` anywhere in the flake
4. Optionally expose it as a flake output in `flake.nix` under `packages`
## Notes
- For unfree or binary packages, set `meta.license` and `meta.sourceProvenance` accurately
- Use `stdenvNoCC` for prebuilt binaries that don't need compilation
- Hash updates: use `nix hash file --type sha256 --sri <file>` after downloading the new binary
+34
View File
@@ -0,0 +1,34 @@
# secrets/
Age-encrypted secret files managed with [agenix](https://github.com/ryantm/agenix).
## Contents
| File | Description |
|---|---|
| `dns-addresses.conf.age` | DNS address overrides for the dnsmasq module |
| `glmain.json.age` | OpenWrt router credentials/config for `glmain` |
## ⚠️ Agent Warning
**Do not read, write, decrypt, or delete any `.age` file.**
These files are encrypted and can only be decrypted by authorized SSH keys.
Editing them outside of `agenix` will corrupt the secret.
## Workflow (for humans)
```bash
# Edit a secret (decrypts, opens editor, re-encrypts)
skyg secrets edit dns-addresses.conf.age
# Re-key all secrets (e.g. after adding a new host key)
skyg secrets rekey
```
## Adding a New Secret
1. Add the `.age` filename and authorized public keys to `secrets.nix`
2. Run `skyg secrets edit <name>.age` to create and encrypt the file
3. Reference it in a module via `config.age.secrets.<name>.path`
See `docs/agenix.md` for the full workflow reference.
+18
View File
@@ -0,0 +1,18 @@
# system-special-links/
Tracked repository copies of files that live at special system paths outside the normal
Nix store — primarily Kubernetes configs and persistent service data that must be
version-controlled but can't be managed as Nix derivations.
## Contents
| Directory | Description |
|---|---|
| `k3s-configs/` | K3s cluster configuration files (manifests, kubeconfig templates) |
| `terra1-apps/` | Application data layouts for `hl-terra1` NFS-backed services |
## Notes
- Files here are **not** automatically deployed by the flake
- They are synced to target hosts manually or via the `skyg remote` workflow
- Do not store secrets here — use `secrets/` with agenix instead