current build
This commit is contained in:
1 parent
842ac07091
commit
c031fc7ae1
11 files changed
+401
-1
No files matched your search
+141
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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`
|
||||
@@ -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
@@ -1,4 +1,5 @@
|
||||
{ pkgs
|
||||
, lib
|
||||
, ...
|
||||
}:
|
||||
let
|
||||
@@ -154,7 +155,6 @@ in
|
||||
OLLAMA_KEEP_ALIVE = "24h";
|
||||
};
|
||||
};
|
||||
hardware.graphics.enable = true;
|
||||
hardware.enableAllFirmware = true;
|
||||
hardware.amdgpu = {
|
||||
opencl.enable = true;
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
Reference in new issue
Block a user