KioskConfig/AGENTS.md

AGENTS.md

What this repo is

NixOS flake that defines kiosk systems running the RadiantWave app. Not application code — this is the OS image and deployment configuration. The actual app lives in the radiantwave flake input (from gitea.radiantwavetech.com).

Hosted on Gitea: https://gitea.radiantwavetech.com/RadiantWaveTech/KioskConfig

Key commands

# Build a system closure (any config name from flake.nix)
nix build .#nixosConfigurations.<name>.config.system.build.toplevel

# Build a bootable ISO
nix build .#nixosConfigurations.<name>.config.system.build.isoImage

# Deploy to a remote kiosk over SSH
nixos-rebuild switch --flake .#<name> --target-host root@<host>

# Push build result to Attic cache
attic push kiosk ./result

# Evaluate available config names
nix eval .#nixosConfigurations --apply builtins.attrNames

Config variants

Name	Target hardware	Disk device	Notes
radiantwavekiosk	Intel NUC 14 (NVMe)	/dev/nvme0n1	Production, uses radiantwave main
radiantwavekiosk-dev	Intel NUC 14 (NVMe)	/dev/nvme0n1	Dev, uses radiantwave-dev ref
radiantwavekiosk-commercial	Commercial HW (SATA)	/dev/sda	Production
radiantwavekiosk-commercial-dev	Commercial HW (SATA)	/dev/sda	Dev
radiantwavekiosk-android	Intel NUC 14	/dev/nvme0n1	+ rotated display (portrait)
radiantwavekiosk-rpi	Raspberry Pi 5	—	Uses nixos-raspberrypi
radiantwavekiosk-rpi-dev	Raspberry Pi 5	—	Dev, uses radiantwave-dev

ISOs: usb-iso, commercial-usb-iso, android-iso, dev-iso — each bakes in the corresponding system closure for zero-touch install.

Branching model

Single branch (main). Production vs. dev split is at the flake input level (radiantwave vs radiantwave-dev), not at the branch level.

CI (Forgejo)

.forgejo/workflows/build-dev.yml — triggered by repository_dispatch (radiantwave-dev-built) from the RadiantWave repo. Updates radiantwave-dev input, builds dev closure + ISO, commits updated flake.lock. Runs on neils-server-runner.

Important gotchas

• Disk device differs by variant: disk-config.nix uses /dev/nvme0n1, commercial-disk-config.nix uses /dev/sda. Don't mix them up.
• ISO configs reference specific system closures: iso-config.nix hardcodes radiantwavekiosk, dev-iso.nix hardcodes radiantwavekiosk-dev, commercial-iso-config.nix hardcodes radiantwavekiosk-commercial. Changing a config name in flake.nix requires updating the corresponding ISO config.
• Attic cache token: ISO configs embed a JWT token for Attic in /etc/nix/netrc. If builds fail with auth errors, the token may have expired (expiry in the JWT payload).
• rotated_display.nix uses mkForce on loginShellInit — it replaces the entire kiosk startup script from configuration.nix, don't edit both.
• SOPS: .sops.yaml configures age-based encryption for secrets.yaml. You'll need the private key matching age1t2wpzv... to decrypt.
• Flake inputs: radiantwave tracks main, radiantwave-dev tracks ?ref=dev. Updating them independently is intentional.

File map

• flake.nix — all system definitions, entry point
• configuration.nix — shared NixOS config (packages, services, kiosk user, auto-upgrade, health check, VM variant)
• disk-config.nix — NVMe disk layout (NUC)
• commercial-disk-config.nix — SATA disk layout (commercial HW)
• iso-config.nix — production ISO + zero-touch installer
• dev-iso.nix — dev ISO + zero-touch installer
• commercial-iso-config.nix — commercial ISO + zero-touch installer
• rotated_display.nix — portrait display override for Android variant
• facter.json — hardware facter report (NUC 14)
• 14rvk.json, pn54.json — additional hardware facter reports
• assets/ — logo and splash image
• plymouth-theme/ — boot splash theme
• commands.md — quick-reference for build/deploy commands