Skip to content
schiffy91Public

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

1,821 Commits

Folders and files

Repository files navigation

Machine configuration

This repository configures NixOS and macOS machines in config/hosts, with local management tooling written in BTRC. System management, application tooling, CI orchestration and test scenarios use Nix and BTRC. Native bindings handle operating-system and library boundaries. Upstream build tools, including the pinned BTRC compiler and Wine generators, may still depend on Python.

Current Hosts

Host System Purpose
FRACTAL-NORTH x86_64-linux Main desktop/workstation configuration
STEAM-DECK-OLED x86_64-linux Steam Deck OLED on Jovian-NixOS
QEMU aarch64-linux Declarative ARM guest used for Nix evaluation and VM-oriented testing
QEMU x86_64-linux Declarative x86 guest used for Nix evaluation and VM-oriented testing
mbp21 aarch64-darwin MacBook Pro

Each Linux host is exposed with bootable NixOS targets and disk-operation disko targets:

Target suffix Purpose
Standard-Boot Full system with systemd-boot
Secure-Boot Full system with Lanzaboote secure boot
Disk-Operation Disk layout only, exposed under diskoConfigurations for disko

Examples:

nix eval .#nixosConfigurations.FRACTAL-NORTH-Standard-Boot.config.system.build.toplevel.drvPath
nix eval .#nixosConfigurations.QEMU-aarch64-Standard-Boot.config.networking.hostName
nix eval .#nixosConfigurations.QEMU-x86_64-Standard-Boot.config.networking.hostName
nix eval .#diskoConfigurations.QEMU-x86_64-Disk-Operation.disko.devices.disk.main.device

Disk-Operation targets are disko entrypoints, not installed boot targets. They use config/outputs/diskOperations.nix to apply the resolved host disk settings to config/system/nixos/disk.nix. They do not import unrelated host services or appear under nixosConfigurations.

Repository Layout

Path Purpose
flake.nix Pinned inputs and the entry point into config/outputs/
config/outputs/ Host registry, system and home configurations, disk operations, installers, and checks
config/outputs/systems.nix Names the system and package modules each platform is built from
config/home.nix Home Manager module composition
shell.nix Direnv-friendly dev shell with btrcpy, btrc-lsp, Nix tooling, Git, and a C toolchain
config/settings.nix Entry point importing the system and package option catalogs
config/system/options.nix Shared core options and imports for domain-owned system schemas
config/system/nixos/ NixOS system modules, listed in its default.nix
config/system/darwin/ nix-darwin modules applying Mac settings, listed in its default.nix
config/pkgs/de/kde/home.nix Linux Plasma Home Manager integration
config/pkgs/dev/ Shared development tools, shell/Git Home Manager settings, and agent configuration
config/pkgs/ Explicit development, desktop environment, gaming, and utility module catalogs
config/pkgs/gaming/ Game modules, runtime source, packages and assets colocated by feature
config/hosts/x86_64/FRACTAL-NORTH/ Main workstation host modules and host-specific data
config/hosts/x86_64/STEAM-DECK-OLED/ Steam Deck OLED host on Jovian
config/hosts/aarch64/QEMU/ ARM QEMU guest host modules
config/hosts/x86_64/QEMU/ x86 QEMU guest host modules
config/pkgs/utils/nixosctl/ Management CLI, lib/ runtime implementation, and ui/ tray application
config/system/storage/immutability/src/ BTRC immutability entrypoint and engine modules
config/pkgs/utils/nixosctl/lib/core/ Shared BTRC helpers used by nixosctl, tests, and immutability
build/ Gitignored local compiler intermediates and binaries
tests/ Declarative VM e2e graph, per-scenario specs, and flake checks
Makefile Root build/test contract (make build, make check, make -C tests graph-*)
ci/ Cache publishing, CI target definitions, and local.json: the jobs a local pass may stand in for
.github/workflows/ GitHub-required workflow entry points calling ci/

Host discovery checks exactly two directory levels:

config/hosts/<architecture>/<HOST>/default.nix

config/outputs/hosts.nix records platform exceptions such as mbp21 on Darwin. lib.hosts exposes only physical Linux hosts to the installer picker; test adapters under tests/hosts still receive system and installer outputs. Duplicate QEMU names retain their architecture suffixes. Existing saved host paths are resolved to the new entry locations by nixosctl.

Settings Model

config/settings.nix composes config/system/options.nix and config/pkgs/options.nix. Option definitions live beside their owning features: users, storage, immutability, boot, sleep, networking, macOS, and individual packages. The existing settings.* names remain the stable configuration interface. Host modules should prefer overriding these options instead of directly changing shared modules whenever a value is host policy rather than module structure.

Important setting groups:

Setting prefix Purpose
settings.users.admin.* Admin username, public identity, authorized keys, autologin, lock behavior, Home Manager enablement
settings.users.agent.* Isolated agent user, packages, SSH keys, and persisted workspace/cache paths
settings.disk.* Disk device, partition labels, btrfs subvolumes, swap, encryption, immutability
settings.boot.* Boot method, kernel, Plymouth, secure-boot PKI bundle and key re-enrollment, generation limit, timeout
settings.sleep.* Hibernation, and whether suspend requests hibernate instead (implies hibernation)
settings.tpm.* TPM2 device and version paths
settings.desktop.* Default session, display outputs, cursor theme/package/path, Plasma theme values
settings.apps.* Optional app policy flags
settings.networking.* LAN subnet, firewall port intent, SSH identity agent, primary NIC
settings.input.* Libinput mouse overrides
settings.apps.gaming.rocksmith.* Audio buffer/sample rate used by Steam/Rocksmith and low-latency PipeWire config
settings.apps.gaming.cpuAffinity Optional Linux CPU list for Steam games and Battle.net; null keeps normal scheduling
settings.apps.utils.nixosctl.* Structured display/audio settings, generated TOML config path, default-on idle inhibit
settings.apps.gaming.sunshine.* Capture backend (kms or kwin), CUDA build, KWin virtual display
settings.networking.forwardAgentHosts Explicitly trusted SSH agent-forwarding destinations
settings.networking.wifi.backgroundScan.* When a connected Wi-Fi device looks for a stronger access point: signal threshold, intervals, or never

Gaming CPU affinity and power profiles

settings.apps.gaming.cpuAffinity = "0-7,16-23"; starts managed Steam games and Battle.net on the first CCD of FRACTAL-NORTH's Ryzen 7950X, including its SMT threads. CPU numbering is host-specific; other hosts default to null. Steam's per-game launch options remain intact inside the wrapper. Steam must be closed during activation so its configuration can be updated. Restart Battle.net and any running games to inherit the new affinity.

game-run COMMAND ... applies the same policy to other launchers. Set GAME_CPU_AFFINITY=all before the wrapper to skip applying the policy for one launch, or set the Nix option to null and rebuild to disable it globally. This sets inherited scheduling affinity; applications can reset their own thread affinity. It does not reserve those cores or promise higher frame rates.

The nixosctl tray's CPU submenu lists the power profiles advertised by power-profiles-daemon and marks the active one. Selecting Performance, Balanced, or Power Saver changes the profile immediately through the normal desktop authorization. Unavailable profiles are omitted. The CLI equivalents are nixosctl power list, nixosctl power current, and nixosctl power set performance. nixosctl power is performance returns success only while that profile is active. These controls do not change GPU power limits or clocks.

App Flags

Application settings follow their category: apps.dev.vscode, apps.gaming.steam, and apps.utils.chrome. Modules check only their own enable switch. Nix validates the hierarchy before building or activating it; there is no runtime enablement resolver.

Default-on children inherit their parent's enablement. Optional tools such as LM Studio and Antigravity default off. An explicit true under a disabled parent is an error, including mkForce true; either disable that child or enable its parent. Non-enable configuration (URLs, paths, preferences) may remain declared while an app is disabled. For example, this is rejected:

settings.apps.dev.enable = false;
settings.apps.dev.vscode.enable = true;

The error names both settings. Disabling a category in a host that explicitly enables children requires changing those child settings too; it does not silently override the host's declared intent. Common defaults are:

settings.apps.enable = true;
settings.apps.dev.enable = true;
settings.apps.gaming.enable = true;
settings.apps.utils.enable = true;
settings.apps.dev.agents.enable = true;
settings.apps.utils.onePassword.enable = true;
settings.apps.dev.bash.enable = true;
settings.apps.gaming.battlenet.enable = true;
settings.apps.dev.claude.enable = true;
settings.apps.dev.codex.enable = true;
settings.apps.utils.drive.enable = true;
settings.apps.dev.git.enable = true;
settings.apps.utils.nixosctl.enable = true;
settings.apps.gaming.rocksmith.enable = true;
settings.apps.gaming.steam.enable = true;
settings.apps.gaming.sunshine.enable = true;
settings.apps.dev.vscode.enable = true;

Sibling dependencies are checked during evaluation too. Assetto Corsa, Battle.net, and Rocksmith require settings.apps.gaming.steam.protonCustom.enable and x86_64 Linux; WoW requires Battle.net. Their defaults follow those dependencies. Sunshine's CUDA build is opt-in through settings.apps.gaming.sunshine.cuda.enable; other hosts keep the non-CUDA build. Both builds require provisioned administration credentials.

Chrome PWAs have individual switches and stable taskbar references:

settings.apps.utils.chrome.webApps.mail = {
  enable = true;
  name = "Mail";
  url = "https://mail.example.com/";
};
# Taskbar reference: config.settings.apps.utils.chrome.webApps.mail.launcher

Omitting a PWA's enable makes it follow Chrome. Setting it to false removes its installation policy and managed launcher. Enabled PWAs under disabled Chrome are rejected just like other children. The validator discovers enable options from the module schema, so newly declared apps need no separate registry.

Plasma desktop state is intentionally not treated as an optional app flag. It is part of the shared desktop surface, not an app install.

System Modules

Boot

config/system/nixos/boot.nix selects behavior from settings.boot.method.

Method Behavior
Standard-Boot Enables systemd-boot
Secure-Boot Disables systemd-boot directly and enables Lanzaboote
Disk-Operation Not handled by this module; the flake exposes config/system/nixos/disk.nix through diskoConfigurations

The shared boot module sets current kernel packages, Plymouth, quiet boot parameters, the EFI mount point, and settings.boot.previousGenerationLimit as the loader's configurationLimit. The initrd is systemd's — scripted stage 1 no longer exists in nixpkgs — and the module only orders plymouth-start.service after systemd-modules-load.service inside it.

Standard-Boot Safety Guard

config/system/nixos/boot/safety.nix refuses to write unsigned boot files while the firmware has Secure Boot enabled. It reads SecureBoot-8be4df61-93ca-11d2-aa0d-00e098032b8c from efivarfs and fails activation when the byte says enabled, and equally when the state cannot be determined — an unmounted efivarfs is not treated as "no Secure Boot". The guard runs in two places, because they are two different bypasses:

Hook Covers
system.preSwitchChecks.secureBoot nixos-rebuild switch on a running system
system.build.installBootLoader wrapper nixos-install and NIXOS_NO_CHECK, before the first ESP write

It is active only when settings.boot.method == "Standard-Boot"; the guard itself is also exposed as the bootSafety module argument. Switching a Secure-Boot machine back to Standard-Boot therefore requires disabling Secure Boot in firmware first, which is deliberate: the alternative is an ESP full of unsigned files that the firmware will not boot.

Recovery

settings.disk.recovery.enable = true adds a RECOVERY vfat partition to the destructive disko layout and enables the nixos-recovery-boot-entry service on installed systems. The recovery image is not a downloaded ISO; it is a self-contained NixOS netboot environment built from config/system/nixos/recovery.nix. Secure-Boot embeds it in a signed unified kernel image.

On switch, the service requires /boot and /recovery to be mounted, then installs:

Path Purpose
/boot/EFI/recovery/nixos-recovery.efi signed unified recovery image in Secure-Boot
/boot/EFI/recovery/kernel.efi, initrd split recovery payload in Standard-Boot
/boot/loader/entries/nixos-recovery.conf systemd-boot/Lanzaboote menu entry
/recovery/EFI/recovery/nixos-recovery.efi independently bootable signed recovery image
/recovery/EFI/recovery/kernel.efi, initrd split recovery payload in Standard-Boot
/recovery/EFI/BOOT/BOOT*.EFI recovery partition systemd-boot fallback
/recovery/loader/entries/nixos-recovery.conf direct-firmware fallback menu entry

Standard-Boot uses a split kernel/initrd. Secure-Boot uses a signed unified image that authenticates the kernel, initrd and command line together. It also signs the fallback loader with the configured db key. Installed checksums and signatures are checked before skipping an update; files are staged before replacement. Missing mounts fail the recovery service. Updating the recovery image is a rebuild. Changing the recovery partition size on an already-installed disk is a real partition resize operation, not something this config does online.

Recovery boots include nixos-mount. Run it after SSH or local console access to unlock the root LUKS device if needed, mount the installed system at /mnt, mount persistent subvolumes that exist, and mount /boot plus /recovery:

nixos-mount

For an existing machine such as FRACTAL-NORTH, do this from a live environment after backup and disk inspection. The desired end state is:

Partition Size Label Purpose
ESP 4G disk-main-boot normal systemd-boot/Lanzaboote boot partition
Root remaining space disk-main-root existing LUKS/Btrfs root
Recovery 4G disk-main-recovery recovery boot partition

If there is already free space, creating recovery is straightforward:

sgdisk -n 0:0:+4G -t 0:EF00 -c 0:disk-main-recovery /dev/nvme0n1
mkfs.vfat -F 32 -n RECOVERY /dev/disk/by-partlabel/disk-main-recovery

If the existing ESP is too small, do not try to grow it in place when root sits after it. Instead shrink Btrfs and the root partition offline, rename the old ESP to disk-main-boot-legacy, create a new 4G disk-main-boot ESP near the end of the disk, and create the 4G disk-main-recovery partition beside it. After /boot and /recovery mount, rebuild or install from the mounted system; the recovery service populates the recovery kernel, initrd, fallback bootloader, and boot entry.

When the newest generation does not boot

Nothing has to be repaired from outside. The boot menu keeps the earlier generations, up to settings.boot.previousGenerationLimit:

  1. Power the machine off and on. In the boot menu, move to the entry below the first (j or the down arrow) and press Enter. That is the generation that ran before the update.
  2. Once it is up, undo or fix the change in /etc/nixos that broke the boot.
  3. Run nixosctl update. The generation it builds becomes the default, and the next plain reboot takes it.

Persisted data and the machine's identity are untouched by the failed boot. The recovery-bad-generation node does exactly this in a VM: a generation whose initrd fails, the previous entry chosen from the menu, the change removed, nixosctl update, and a plain reboot. With a generation limit of 1 there is no earlier entry to choose, and the node fails. The recovery system above is for a disk that no generation can boot.

Disk

config/system/nixos/disk.nix owns the disko layout. The default model is:

Layer Default
Partition table GPT
EFI partition settings.disk.boot.size (4G), vfat, mounted at settings.disk.boot.efiSysMountPoint
Root partition btrfs, optionally wrapped in LUKS
Subvolumes @root, @home, @nix, @var, @snapshots, @swap

The QEMU host overrides the disk to /dev/vda, disables encryption, enables the immutability reset workflow, and sets a small swap size suitable for VM use.

Optional boot-passphrase reuse is configured with settings.disk.encryption.opportunisticUnlock.enable. It discovers attached software LUKS volumes across storage transports, skips root and already-open backing devices, and unlocks matching volumes without mounting them. The verified passphrase is consumed from a short-lived kernel key; TPM-only/keyfile boots and later hotplug do not trigger attempts. See the policy and boot regression gates for eligibility and resource limits.

External storage

settings.disk.storage.<name> declares an encrypted external volume: an SD card, a USB drive, on any host. config/system/nixos/storage.nix gives each one a LUKS2 container opened by a key file whenever the device appears, at boot or later, and an ext4 filesystem mounted at its mount point; a volume that is not attached costs boot nothing, and a pulled one comes off its mount point at once.

Setting Default Meaning
label the name The filesystem's label; the container's is <label>-crypt
mountPoint /<name> Where it is mounted
keyFile /var/lib/nixos/storage/<name>/key Root-only key on the system disk, in a persisted folder; a copy of the LUKS header is kept beside it
library, driveFolder empty The one folder an unprepared device may hold and still be formatted, and where that folder is on the Drive; every file must be there
steamLibrary false Where there is a Steam: a folder steam on the volume, which a running Steam is told about when the volume arrives

nixosctl storage works on a declared volume by its name; the name may be left out on a machine that declares one:

nixosctl storage status                        # every declared volume
sudo nixosctl storage prepare usb /dev/sda1    # format, encrypt, mount; asks first, refuses a device with files it may not lose
sudo nixosctl storage password usb /dev/sda1   # a second way in, for other machines and a reinstall
sudo nixosctl storage open usb /dev/sda1       # by hand, with the password
sudo nixosctl storage key usb /dev/sda1        # a new key file for a machine that lost its own

The Steam Deck's card is the volume sdcard (label SD, mounted at /sd, holding the emulation library through the Drive client, with a Steam library beside it). The storage VM scenario runs a card and a USB drive side by side.

Immutability

config/system/storage/immutability/default.nix drives the BTRC immutability, the sole immutability implementation. Its source entrypoint is config/system/storage/immutability/src/Immutability.btrc; Nix builds it with the flake-locked BTRC compiler and a generated stdlib archive.

The initrd reset runs after systemd-hibernate-resume.service. A successful resume never returns to the initrd, so the reset only runs on a fresh boot and never rewrites the filesystem underneath a hibernated kernel. That ordering is the whole reason hibernation is safe on an immutable root, so it is asserted in the app-settings check for every host that hibernates.

Resume itself needs no kernel command line, even with the swap file on btrfs: systemd-hibernate writes the device and offset into the HibernateLocation EFI variable and the initrd generator reads it back, so boot.resumeDevice stays empty. See the Steam Deck README for why adding resume= by hand makes this worse rather than better.

Mode Behavior
converge Default. Same rollback as reset; the two names are interchangeable in Immutability.resetMode()
reset Roll each resetOnBoot subvolume back to its read-only CLEAN snapshot at boot
prepare-only Build NEXT from CLEAN and persisted state without publishing it
publish-prepared Publish an existing prepared NEXT at boot without rebuilding it
snapshot-only Rotate snapshots without rolling back (ephemeral survives)
restore-previous / restore-a Roll back to generation 1
restore-penultimate / restore-b Roll back to generation 2
restore-c Roll back to generation 3
restore-generation Roll back to settings.disk.immutability.restoreGeneration
disabled No reset

Any other value is fatal in the initrd (Unknown mode:), so the enum in config/system/storage/immutability/options.nix and ImmutabilityConstants must stay in step.

enforce.onReboot wires the initrd reset + mounts service. Updates do not rewrite the CLEAN baseline from the running root; the boot-time reset path is the only automatic immutability reconciliation path.

For a more inspectable reset, run the live preparation path before switching the boot mode:

sudo nixosctl immutability plan
sudo nixosctl immutability prepare

plan prints the resolved keep plan from the installed config. prepare mounts the btrfs top level, rotates generations, and builds NEXT while the current system keeps running. Setting settings.disk.immutability.mode = "publish-prepared" then makes initrd only verify and publish that prepared snapshot. Runtime logs are also written under @snapshots/.immutability/logs/.

The v2 mode persists selected files/directories by materializing persistent btrfs subvolumes under @persist and bind-mounting selected targets after reset. The source-of-truth persist list is settings.disk.immutability.persist.paths.

This option starts with an empty list. System modules contribute core state, and enabled package modules contribute their own state through ordinary Nix list definitions. The merged result removes exact duplicates. Shared desktop state belongs to the desktop module, so disabling Chrome or Sunshine does not remove shared icon, application, or desktop state. Persistence contributions remain available when settings.disk.immutability.enable = false; the separate settings.disk.persistence.enable flag controls persistent mounting.

For example, Sunshine contributes its configuration directory inside its enabled module. A host can add paths in the same way, including state it wants to retain while a package is disabled:

settings.apps.gaming.sunshine.enable = false;
settings.disk.immutability.persist.paths = [
  "${config.settings.users.admin.homeDirectory}/.config/sunshine"
];

Package contributions follow their app and group switches. Turning a feature off removes its paths from the active specification unless another module retains them. The next prepare/reset quarantines unused stores; re-enabling the feature does not automatically recover those stores. Keep an explicit host contribution for temporary disablement, or use the materialization workflow below when retiring persistence. The persistence-ownership and immutability-feature-disable graph checks cover merging, feature switches, quarantine, recovery, and retention.

Persist stores use reversible keys: the absolute path without its leading slash is URL-escaped, then encoded path separators are written as !. For example, /home/alex/name with spaces becomes home!alex!name%20with%20spaces. Persisted directories live under @persist/dirs; persisted files live under @persist/.immutability/files.

The reset path records the active immutability state version in @snapshots/.immutability/version, mounted at /.snapshots/.immutability/version after boot. The current version is 2026.08.22; any future version-specific transition belongs in config/system/storage/immutability/default.nix.

settings.disk.immutability.nonPersistedGenerations controls how many reset generations are retained. The default 3 preserves the old effective behavior; 0 keeps no non-persisted rollback generations. Restore modes assert that the configured retention count is high enough for the requested generation.

When a persisted path should become ordinary immutable state, edit the config first, but run materialization before rebuilding into that new spec:

sudo nixosctl persistence materialize --refresh-clean
sudo nixosctl update

The command uses the currently installed /etc/immutability/spec.toml, copies the still-persisted data back into its reset subvolume, and refreshes CLEAN. The following rebuild then removes the path from the generated spec. Running the rebuild first loses the old spec and leaves no declarative way to know what should be copied back.

Common path transitions:

User flow Handling
Enable immutability with n paths Rebuild; first reset creates canonical @persist stores and mounts selected paths
Add a persisted path Rebuild; reset creates the store from live or CLEAN data when it exists
Remove a persisted path Edit config, run nixosctl persistence materialize --refresh-clean, rebuild; stale dir/file stores are quarantined on the next reset
Rename or move a persisted path Treat as remove old + add new; materialize/checkpoint the old path before rebuilding
Disable immutability but keep persistence Rebuild; reset stops, but persistence-mounts can still mount configured stores
Disable persistence or clear all paths Materialize/checkpoint before rebuilding if data should remain in place
Upgrade immutability Rebuild; persist keys are canonical-only in this tree
A configured path no longer exists auto resolves to file unless a trailing slash or kind = "dir" declares a directory; missing stores remain absent
Directory becomes file or file becomes directory Resolved plans keep only the matching store kind; the old kind is quarantined as an orphan

Orphans are reviewable state, not silent deletion. Directory stores move under @persist/.orphans/<key>-<stamp> and file stores stay in their file-store subvolume under @persist/.immutability/files/.orphans/<stamp>/<key>.

Desktop

config/pkgs/de/kde/default.nix enables the Plasma 6 Wayland desktop, SDDM, dconf, graphics, cursor packages, and selected KDE integrations. The display manager starts settings.desktop.defaultSession.

config/pkgs/de/kde/ owns the Plasma system module, Home Manager configuration, KDE option definitions, and persistence paths. Shared desktop options live in config/pkgs/de/options.nix; their existing settings.desktop.* names are unchanged.

Host-specific desktop state lives in the host modules. FRACTAL-NORTH and Steam Deck use default.nix entries that explicitly import system/ and pkgs/. Package selections and hardware-specific overrides live in pkgs/default.nix, while shared application implementations live under config/pkgs/. Supporting assets stay beside their modules. The smaller Mac and QEMU hosts use one default.nix each.

File Role
config/hosts/x86_64/FRACTAL-NORTH/system/gpu.nix NVIDIA/AMD graphics setup, device symlinks, KWin DRM devices
config/hosts/x86_64/FRACTAL-NORTH/system/audio.nix Low-latency PipeWire and device-specific audio rules
config/hosts/x86_64/FRACTAL-NORTH/system/input.nix Controller and mouse receiver support

Networking And Security

config/system/nixos/networking.nix owns NetworkManager, firewall rules, mDNS, OpenSSH, SSH agent forwarding, and optional primary-interface enforcement. Firewall LAN allow rules are derived from shared service flags and settings.networking.ports.{tcp,udp}.

While connected, wpa_supplicant leaves the channel to look for a stronger access point, and a sweep of every band stalls traffic for several seconds: a stream or a controller link stutters. NetworkManager decides when. For a network with several access points that is whenever the signal is under -65 dBm and every five minutes regardless, the defaults of settings.networking.wifi.backgroundScan. A host that changes signalThreshold, weakSignalInterval or recurringInterval (null for no recurring scan), or sets enable = false, has its policy given to wpa_supplicant after each connection, and on a switch to the connection that is up. NetworkManager has no setting of its own for this. Below the threshold a device scans every weakSignalInterval seconds for as long as the signal stays weak.

config/outputs/systems.nix builds every Linux host from config/system/nixos, config/pkgs and config/pkgs/de/kde; config/system/nixos/default.nix lists the system modules. config/system/nixos/users.nix imports Home Manager and defines immutable users: the interactive admin account and an isolated agent account with its own Home Manager profile and tool set. User mutability is disabled, so password changes must update the hashed password file and rebuild.

settings.users.admin.hashedPasswordFile defaults to /var/lib/nixos/credentials/password-hash. Its directory is root-owned 0700, the file is root-owned 0600, and every parent must be root-owned and not writable by other users. Installation copies it explicitly; immutable-root systems mount the persistent /var subvolume before activation. Password updates use an exclusive lock and durable atomic replacement. The configuration rejects a credential location that would disappear during an immutable-root reset or be mounted too late for activation. Restoring an older root snapshot keeps the current password from persistent storage. The containing mounts must be required (nofail and noauto are rejected), and the hash itself cannot be a bind mount because updates replace it atomically.

Use nixosctl change-password for persistent password changes. A direct passwd changes the running account only; with immutable users, activation restores the authoritative hash on rebuild or boot. Disk, running-account and persistent-password changes are separate operations. If saving the persistent hash fails after the account changes, the CLI explains that reboot may restore the previous account password while keeping a completed disk-password change. Rerun change-password with the intended new password to finish; it skips components that already accept that password. If only the final rebuild fails, the new hash is already saved; run nixosctl update before rebooting so the booted generation uses that authority rather than a legacy repository hash.

The installer uses /run/nixosctl-install/passphrase for the temporary LUKS passphrase. It creates the directory as root-only 0700 and the file as 0600 before writing, rejects unsafe existing files and ancestors, and removes a file it created after disk preparation, including ordinary failure paths. A hard kill can leave the protected file until reboot; /run is temporary. A securely pre-provided file is preserved for its caller. Custom settings.disk.encryption.plainTextPasswordFile paths must meet the same ownership and permission rules; shared writable directories such as /tmp are rejected. Supplied files must contain the exact passphrase bytes, without a trailing newline, CR, or NUL, and at most 511 bytes (the account-hash limit, also within the unlock PAM limit). A supplied file takes precedence over a hash left by an earlier installer attempt so disk and account passwords agree. The limit applies to new passwords; a longer existing LUKS passphrase can still be supplied to change-password when rotating it to a supported new password.

On the first upgrade, the helper preserves the effective password from /etc/shadow if the new file does not yet exist. It does not trust the legacy file in the editable repository. Missing or unsafe credentials abort activation before account updates. Old generations still use their original password-file configuration; retain their legacy file until those generations are retired.

Administration uses ordinary sudo authentication, including the configured 1Password SSH agent. The separate agent account has no administrative access. Local admin shells select 1Password's socket through SSH_AUTH_SOCK, which sudo's PAM module needs independently of SSH's IdentityAgent setting. SSH sessions retain their forwarded agent. For a terminal opened before this configuration was activated, run export SSH_AUTH_SOCK="$HOME/.1password/agent.sock".

Every host trusts one SSH key, the SSH Key item in 1Password's Private vault, declared once in settings.users.admin.authorizedKeys. The Mac declares the same key for Remote Login (settings.macos.remoteLogin.enable, public keys only), points ssh at 1Password's agent, and links launchd's SSH_AUTH_SOCK to that agent so programs that ignore ssh_config use it too. The ssh-trust check fails when a host trusts any other key or accepts passwords.

Sunshine supports administration with the SSH keys held in your local 1Password agent. Enable settings.apps.gaming.sunshine.sshLogin.enable; its public keys default to settings.users.admin.authorizedKeys. Existing Sunshine passwords keep working, and a new instance needs no shared password. Sign in by running the browser's displayed helper command and approving the agent signature. See Sunshine administration for public-key files, certificate trust, exact commands, session limits and VM checks.

For password login, Sunshine administration credentials are declared with settings.apps.gaming.sunshine.credentials.usernameReference and passwordReference. Defaults reference the username and password fields of Sunshine HOSTNAME in 1Password's Private vault. Enable 1Password's Developer → Integrate with 1Password CLI setting, then run as the configured desktop user:

nixosctl sunshine sync
nixosctl sunshine status
systemctl --user restart sunshine

Secrets are retrieved only by the explicit sync command. The local salted verifier is stored atomically in the user's private .config/sunshine/credentials.json, allowing offline startup. Existing valid credentials are imported from sunshine_state.json on first service start; Moonlight pairings, host identity, and certificates stay in their original files. Updating credentials does not rewrite that pairing state. Without SSH keys, missing or invalid credentials prevent Sunshine from opening its first-run administration interface, including when launched directly. Configured SSH keys protect first-run account creation by requiring SSH authentication.

For remote provisioning, nixosctl sunshine provision accepts a JSON object with username and password through stdin. Feed it through a private pipe from the credential provider; do not place secret values in command arguments, shell history, files, or chat. Run it as the remote desktop user, then restart that user's Sunshine service. Vault retrieval failures leave existing credentials intact.

settings.networking.identityAgent retains the local 1Password agent. settings.networking.forwardAgentHosts explicitly lists destinations allowed to use that agent remotely; other destinations default to no forwarding. A trusted remote root can use a forwarded agent while connected, so keep this list narrow. Inside an SSH session with a forwarded agent, outgoing SSH/Git uses that incoming agent rather than requiring a second unlocked 1Password app on the remote host.

Secure Boot

settings.boot.method = "Secure-Boot" disables systemd-boot and hands the ESP to Lanzaboote, which signs the unified kernel images with the PKI bundle at settings.boot.pkiBundle (/var/lib/sbctl). boot.lanzaboote.settings.editor is false, so the loader offers no interactive command line to edit.

Enrollment and teardown go through nixosctl, never through raw sbctl:

sudo nixosctl secure-boot status           # current enforcement, ownership, signatures
sudo nixosctl secure-boot prepare          # reuse/create keys and install signed images
sudo nixosctl secure-boot enable           # enroll missing own keys, PK last
sudo nixosctl secure-boot disable          # authenticated PK removal; keep signed images

prepare validates and reuses a complete local PK/KEK/db bundle, creating keys only when none exist. It selects the signed target, rebuilds and switches the system, verifies its boot images, and prints public certificate fingerprints and the signed recovery artifact location. It does not enroll firmware keys. Before preparation or any key change, each firmware database must be absent or contain only the matching local certificate. Foreign or mixed trust is refused before the rebuild; migrating a machine with factory keys requires a separate, deliberate firmware procedure.

enable prepares and verifies images before enrolling missing databases, with PK last. It preserves every existing owned database byte for byte. If all our keys are already enrolled, it verifies the existing configuration without a rebuild or firmware write. An enrolled PK with missing KEK/db is reported as incomplete rather than silently repaired. Enrollment requires Setup Mode when PK is absent. enable and disable accept --no-reboot to suppress their reboot prompt; use status after a restart to confirm actual enforcement.

Verification covers the fallback loader, systemd-boot<arch>.efi, the default boot entry resolved from bootctl --json=short list, and every EFI/Linux/*.efi. When settings.disk.recovery.enable is set it additionally checks the recovery UKI on both the ESP and the recovery partition, plus the recovery partition's fallback loader, with sbverify --cert against our db certificate.

Only our own keys are supported: --microsoft is rejected. Enrollment keeps sbctl's option-ROM checks and does not pass its dangerous bypass flag. A refusal requires investigating the actual firmware and option-ROM requirements, not silently broadening trust. Independently back up the keys, verify restoration, and boot signed external recovery before relying on this workflow on hardware.

disable authenticates removal of PK with its private key. It retains KEK/db, the local signing bundle, the signed target and all signed boot/recovery images. Repeated removal is harmless. It refuses stale enrollment assets, an active enrollment service, unsafe current/booted or retained generations, orphaned UKIs, and ambiguous legacy loader entries. Boot a safe signed generation and prune/rebuild the old menu before retrying. Automatic enrollment is unsupported in repository configurations; the loader explicitly uses secure-boot-enroll off. This prevents a later boot from undoing deliberate PK removal.

status reads firmware state and verifies artifacts without changing keys or configuration. Current enforcement and pending key changes are reported separately: removing PK may still require a reboot, and an enrolled PK alone does not prove firmware enforcement. Switching to Standard-Boot remains a separate operation, guarded against installing unsigned images while firmware still enforces Secure Boot.

Firmware Security Posture

fwupdmgr security is the health check for the platform side of security. FRACTAL-NORTH sits at HSI:1, which is the ceiling for a consumer AM5 board: HSI-2 needs AMD Platform Secure Boot, an OEM fuse ASUS does not burn. The required BIOS settings, the expected report, and the re-check routine after every firmware flash live in config/hosts/x86_64/FRACTAL-NORTH/BIOS.md.

Two facts are easy to forget:

  1. ASUS resets AMD CBS settings on every BIOS flash. Secure Boot and TSME both dropped silently on 2026-05-18 that way. Re-run the checklist after flashing.
  2. The board's ACPI never marks the Thunderbolt 4 root port ExternalFacingPort, so the kernel cannot flag tunneled devices as untrusted. cpu.nix therefore leaves the IOMMU in translated mode (no iommu=pt); that is the only DMA protection Thunderbolt gets on this hardware.

Apps And Package Overrides

config/pkgs/default.nix imports explicit dev, gaming and utility catalogs. Application modules use the validated hierarchy under settings.apps. Groups let lean profiles turn off whole groups: settings.apps.dev.enable, settings.apps.gaming.enable, and settings.apps.utils.enable.

Path Behavior
dev/zsh.nix Makes zsh the admin login shell when settings.apps.dev.zsh.enable is set, leaving compinit to Home Manager
dev/git.nix Enables system Git and GitHub's gh, and persists gh's sign-in (~/.config/gh); per-user identities live in Home Manager
dev/vscode.nix Installs VSCode, the BTRC extension, and btrc-lsp from the flake-locked BTRC package set
gaming/battlenet/default.nix Installs a Battle.net Proton wrapper, desktop entry, and capture helper on x86_64 when Steam is enabled
gaming/proton/default.nix Installs the patched Proton compatibility tool when settings.apps.gaming.steam.protonCustom.enable is set
gaming/rocksmith/default.nix Installs Rocksmith support files and Slopsmith when Steam is enabled
gaming/steam/default.nix Exports Steam tool names, configures installed Steam apps, and installs settings.apps.gaming.steam.shortcuts as non-Steam shortcuts when Steam is enabled
gaming/sunshine/default.nix Sunshine service and ports; the CUDA overlay, and the KWin HDR screencast patch when capture is kwin
gaming/sunshine/virtual-display.nix KWin virtual streaming display and its Desktop/Big Picture apps when virtualDisplay.enable is set
gaming/assettocorsa/default.nix Assetto Corsa content import, CM presets, control bindings, UI scale, and the CSP wheel menu
gaming/simracing/default.nix Enables the logitech-trueforce kernel module on x86_64 for wheel force feedback
gaming/semu/default.nix Installs semu from its flake input, sets SEMU_TARGET (and SEMU_ROOT when root is set), and has the Drive client keep the library's folder (drive) downloaded, leaving Semu's unfinished files out of the sync
gaming/btrsmith/default.nix Installs BTRSmith when an exact flake input provides it
gaming/wine/default.nix wine-prefix-dpi, which writes LogPixels into a prefix registry
utils/1password.nix Installs 1Password GUI/CLI and writes SSH agent config
utils/nixosctl/default.nix Builds + packages the BTRC nixosctl CLI into environment.systemPackages
utils/nixosctl/ui/default.nix Packages the BTRC tray GUI for nixosctl
utils/drive/default.nix The BTRC Google Drive client: ~/Drive served from a real tree behind a FUSE door, an engine that syncs it both ways, pinned folders kept downloaded, folders placed on another volume, the push listener, and on a desktop a tray icon that shows how far a sync is with a window behind it (tray); its plan and measurements are in utils/drive/PLAN.md

The custom Proton tree under config/pkgs/gaming/proton/custom is a large patch-carrying workflow for Battle.net/Wayland/HDR behavior. Keep that area focused and avoid broad formatting churn; its local README has the development loop.

VFIO has been removed from this repo for now because the path was broken and explicitly out of scope for the BTRC rewrite.

BTRC Management Layer

Management runtime source lives alongside its Nix modules under config/pkgs/utils/nixosctl/ and config/system/storage/immutability/. The compiler, language server, and VSCode extension are consumed through the flake input inputs.btrc. The dev shell provides btrcpy and btrc-lsp; local and Nix builds compile with --strict-imports.

That input tracks upstream's default branch; flake.lock records the revision in use and nix flake update btrc moves it.

Path Purpose
config/pkgs/utils/nixosctl/Main.btrc Main CLI (also hosts the VM e2e harness: nixosctl graph / e2e)
config/pkgs/utils/nixosctl/ui/Main.btrc Tray launcher for nixosctl
config/pkgs/utils/nixosctl/lib/btrfs Snapshot and diff helpers for nixosctl
config/pkgs/utils/nixosctl/lib/desktop Audio, display, caffeine, and hardware config commands
config/pkgs/utils/nixosctl/lib/hardware Secure Boot (SecureBootManager + the SecureBootVerification parsers) and TPM2 commands
config/system/storage/immutability/src/Immutability.btrc BTRC entrypoint for the immutability runtime
config/system/storage/immutability/src/lib Immutability runtime library modules
config/pkgs/utils/nixosctl/lib/core Shared logging, path, and interactive helpers
config/pkgs/gaming Independently packaged Steam, Wine prefix, and Assetto Corsa runtime tools
config/pkgs/utils/nixosctl/lib/simulator Declarative VM graph and test runner

BTRC class modules use PascalCase filenames; executable entry points use Main.btrc. The Makefile scans BTRC sources under config/ and tests/. The VM graph hashes workspace source files and the runner binary; source-derived states and their descendants become stale when those inputs change.

Build from the repo root:

make build              # transpile + compile nixosctl and immutability
make clean              # remove gitignored compiler outputs

Common nixosctl commands after build:

build/nixosctl eval config.networking.hostName
sudo build/nixosctl update --upgrade
sudo build/nixosctl install --format
sudo build/nixosctl diff --pattern '/var/*'
sudo build/nixosctl fix-permissions
sudo build/nixosctl secure-boot status
sudo build/nixosctl tpm2 status

On installed hosts the CLI is packaged as nixosctl (see config/pkgs/utils/nixosctl/default.nix) and is on PATH. The native system tray (macOS menu bar / Linux Wayland StatusNotifierItem) is implemented in the BTRC stdlib and packaged by config/pkgs/utils/nixosctl/ui/default.nix.

E2E VM Testing

The BTRC test framework is declarative. Specs live under tests/* and the graph lives at tests/graph.json. The runner is the nixosctl binary itself (nixosctl graph tests/graph.json run <node>).

Core ideas:

Concept Meaning
Spec JSON, TOML, or strict YAML file declaring VM/host operations
Graph node Named spec plus dependencies and optional args
State hash Hash of parent hash, state name, material, and operations
State root .vm/e2e/chain/<state> with recorded hashes and workdir metadata
qcow2 overlay Child VM disk can be reconstructed from parent state without rerunning installation

Useful test targets:

make quick
make harness
ci/checks.sh
make -C tests graph-coverage
make -C tests installer-download
make -C tests installer-ssh
make -C tests graph-full

tests/graph.json is the authoritative node list: its required set names every node that guards a contract, and make -C tests graph-status prints each one with its state (ready, stale, missing, disabled) rather than repeating the list here. A node is switched off, not removed, by giving it a disabled field that says why: it stays in the graph and in required, a run skips it and prints the reason, and no node that still runs may come after it. No node is off at present. The families are installer-*, install-*, immutability-*, recovery-*, secure-boot-*, tpm2-*, boot-*, nixosctl-*, password-change*, and qmp-probe. What only evaluates the configuration (app-settings, qemu-hosts) and the unit suites that are one derivation each are flake checks, built by ci/checks.sh; the graph runner itself is tested by make harness.

Beside required, the graph file names sets, run with nixosctl graph tests/graph.json run-set <name>: aarch64 (make -C tests graph-aarch64) is the install, recovery and Secure Boot chain on an aarch64 guest, native on an aarch64 host and emulated on this desktop, so it is not part of every run here; nightly (make -C tests graph-nightly) holds longer forms of required nodes. deck (make -C tests graph-deck) is the five Gaming Mode sleep and lock nodes, which need a host with exactly one AMD GPU: the Steam Deck has one and this desktop, with its integrated GPU off in firmware, has none. A node without an architecture in its name runs on the host's own. make -C tests starts every run inside its own process namespace where bwrap is installed, so nothing a test signals reaches the session that started it, and a VM whose runner died does not stay behind. The installer-build-* nodes build the installer images the install nodes boot, so a node that boots one holds a VM's memory only while it has a VM.

A node that installs the VM-TEST system does not fetch it from the internet. The run starts one nix-serve on a port from 22600, signing with a key it keeps in .vm/store-key; the node builds its closure on this host and the guest's nixos-install copies it from http://10.0.2.2:<port>. The node fails if the install copied nothing from there, because that means what was built here is not what the guest installed. .vm/e2e/store.log is the server's log.

The nodes with constraints worth knowing before you run them:

  • tpm2-enroll enrolls and wipes a TPM2 LUKS keyslot on an encrypted install.
  • nixosctl-update changes the host's configuration and runs nixosctl update as the admin user, answering "Restart now?" with no. The new generation is the running one and the loader's default, it is still both after a reboot, and that reboot ran the immutability reset without rewriting CLEAN.
  • recovery-bad-generation makes the default generation fail in its initrd, power-cycles the guest, picks the previous generation in the boot menu, and repairs with nixosctl update; the next boot takes the default entry and the persisted data is what it was.
  • tpm2-unlock enrolls with nixosctl tpm2 enable, reboots without typing anything and checks that the console never asked for a passphrase; after nixosctl tpm2 disable the next boot waits at the prompt and takes the passphrase.
  • boot-wrong-passphrase types two wrong passphrases at the boot prompt: the prompt comes back each time and the guest stays unreachable, the right passphrase then boots it, and the LUKS header is byte for byte what it was.
  • immutability-home adds paths in the admin user's home to the persisted set: their content, owner and mode survive two resets, everything else written in that home is gone, and @home keeps its read-only CLEAN snapshot.
  • secure-boot-aarch64 runs the full Lanzaboote flow — install, sign, auto-enroll keys, then bootctl status → Secure Boot: enabled. It needs enforcing firmware, so tests/shell.nix builds Debian's AAVMF_CODE.secboot.fd in a reproducible derivation. addAccelerator picks HVF on a same-arch Mac, KVM on same-arch Linux, and tcg,thread=multi otherwise — so this node is accelerated on the Mac and emulated (slow) on the x86_64 workstation.
  • install-nixosctl builds the packaged CLI, copies its closure into the guest, and runs nixosctl install --format inside the installer ISO. The live ISO keeps its Nix store in RAM, so the node uses 16G, the Deck's memory.
  • immutability-hibernate hibernates and suspends-to-disk an encrypted install and checks that the initrd reset never runs before a resume. It declares no arch, so it runs on the host's architecture. Its guest has one vCPU because QEMU's HVF backend crashes when hibernation offlines secondary CPUs.
  • recovery-secure-boot-* boots the signed recovery UKI, repairs a damaged fallback loader, and reinstalls from recovery.

Encrypted boots use the unlock-luks op: it waits for the LUKS prompt on the serial console, types the passphrase, then waits for SSH. Where a scenario answers the console itself, wait-serial waits for text the guest prints after the last thing typed there (a prompt that is back after a wrong answer, the boot menu), serial-send types, and expect-no-ssh fails if the guest answers SSH at any point in its timeout (a disk still locked, a generation that did not boot). Write negative guest checks as if cmd; then exit 1; fi, because a bare ! pipeline never trips set -e.

Targets that boot QEMU or install NixOS can take time. The early graph is the right default for normal development. The full graph should be used before trusting changes to install, immutability, TPM2, or Secure Boot behavior.

The operation catalog currently has full declared operation coverage through make -C tests graph-coverage. That is operation coverage, not generated-C line coverage.

Development Workflow

Recommended loop:

git status --short
for host in FRACTAL-NORTH-Standard-Boot FRACTAL-NORTH-Secure-Boot \
            STEAM-DECK-OLED-Standard-Boot STEAM-DECK-OLED-Secure-Boot \
            QEMU-x86_64-Standard-Boot QEMU-aarch64-Standard-Boot; do
  nix eval ".#nixosConfigurations.$host.config.system.build.toplevel.drvPath" --show-trace
done
nix eval .#darwinConfigurations.mbp21.config.system.build.toplevel.drvPath --show-trace
nix eval '.#homeConfigurations."alexanderschiffhauer@mbp21".activationPackage.drvPath' --show-trace
make build unit
make -C tests gaming
make -C tests graph-coverage
make harness
ci/checks.sh

Evaluating every bootable target matters after an input bump: a removed NixOS option fails only on the hosts that set it, and the darwin and Home Manager outputs do not share the Linux nixpkgs.

For all flake outputs:

nix flake check --all-systems --no-build --show-trace

For disk-only targets, evaluate disk attributes directly:

nix eval .#diskoConfigurations.QEMU-aarch64-Disk-Operation.disko.devices.disk.main.device --show-trace
nix eval .#diskoConfigurations.QEMU-x86_64-Disk-Operation.disko.devices.disk.main.content.partitions.root.content.type --show-trace

For Nix linting:

nix run nixpkgs#deadnix -- .
nix run nixpkgs#statix -- check .

statix still reports some style-only warnings in dense settings and legacy modules. Prefer fixing warnings when touching nearby code, but do not churn large settings blocks solely for style.

Local passes stand in for CI

A job this machine has already passed for a commit is not run again by GitHub. The tool is schiffy91/ci-local, a flake input here, installed with the dev tools on every host, the Mac included; its README says what counts as a pass and how the workflow reads them. What belongs to this repository:

ci-local run            # every job of this platform; or: ci-local run lint checks
ci-local status         # what is recorded for HEAD
ci-local push           # put the commit on GitHub, post its passes, then git push
  • ci/local.json names the jobs: lint (make lint), checks (ci/checks.sh) and graph (make graph-required). graph is in the table for the record only: the VM graph is too long for a hosted runner, so its status is the only place a commit shows it.
  • checks.yml calls the tool's reusable workflow, pinned by commit, and skips each job whose status the repository's owner posted.
  • The flake check ci-local is the tool's own test, given this repository's table and workflow: every job the table names must be run by the workflow with the same command and skipped on its status.

Binary Cache And Releases

ci/targets.nix is the single list of what gets built, for which systems, on which runners, and what a release carries. Adding a system or an attribute there is the whole change: the Makefile targets, repo-tools publish and both GitHub workflows read that file.

One machine builds for the others, with no account anywhere:

make cache        # this host's ci/targets.nix attrs, signed into ~/.cache/nix-cache
make cache-all    # the `local` list instead: every host's system closure
make cache-serve  # serve that directory over HTTP (CACHE_PORT=8080)

The first run writes ~/.config/nix/nixos-cache-1.key and prints its public half, which is what the other hosts trust. The directory is shared with the other repositories on the host, so one server covers them all. A consumer sets two options:

settings.nix.substituters = [ "http://FRACTAL-NORTH.local:8080" ];
settings.nix.trustedPublicKeys = [ "nixos-cache-1:..." "semu-cache-1:..." ];

config/system/nixos/nix.nix applies them, with connect-timeout = 5 and fallback so a publisher that is switched off costs a build five seconds instead of failing it. STEAM-DECK-OLED is wired this way already: the desktop builds its system and its emulators, and the handheld activates instead of compiling them.

.github/workflows/cache.yml builds one job per system and attribute every Monday and on every push to main, on x86_64 and aarch64 runners. With a CACHIX_AUTH_TOKEN secret it pushes to the Cachix cache named in ci/targets.nix; with a NIX_CACHE_SECRET_KEY secret and no Cachix it signs the closure and leaves a flat cache as a workflow artifact, which nix copy --from file://... consumes unchanged. The NIXOS_CACHE_URL and NIXOS_CACHE_PUBLIC_KEY repository variables let the runners substitute from the cache they are filling.

Architectures split by who can build them. This host builds x86_64-linux only: it has no boot.binfmt.emulatedSystems, so nix reports no aarch64 in extra-platforms and make cache covers x86_64. aarch64-linux comes from CI's ubuntu-24.04-arm runner, and aarch64-darwin from the Mac's own make cache. If you would rather build arm64 here, boot.binfmt.emulatedSystems = [ "aarch64-linux" ] enables it through QEMU, at emulation speed and at the cost of a larger system closure.

.github/workflows/release.yml turns a v* tag into a GitHub Release carrying the installer ISOs in ci/targets.nix release, each with its digest in SHA256SUMS. That list is only the generic installer, which measured 1.9 GB against GitHub's 2 GiB asset limit. A host installer carries that host's whole system closure and every flake input source, so the machine installs with no network and can still evaluate its own configuration afterwards; it measured 13 GB for FRACTAL-NORTH and 11 GB for STEAM-DECK-OLED — past the asset limit and past a hosted runner's disk, so those are in local and travel through make cache instead. The workflow still builds and frees one ISO at a time.

Secrets And Local State

Ignored local paths:

Path Purpose
secrets/ Legacy/local secret material; authoritative account hashes live under /var/lib/nixos/credentials
config.json Local selected host/target for helper tooling
.vm/ QEMU disks, ISO downloads, state graph data
.direnv/, .btrc-cache/, build/ Development caches and build outputs
config/pkgs/gaming/proton/custom/src/ Working Wine tree for the proton-custom dev loop (make shell / make setup)
config/pkgs/gaming/battlenet/tests/.build/ Battle.net test scratch output
result Nix build symlink

Do not commit secret material, VM disk images, installer ISOs, or local build caches.

Migration Notes

The migration to BTRC is complete. Current state:

Area State
CLI dispatch BTRC (nixosctl)
Nix eval/update/install/diff/permissions BTRC
Audio/display/caffeine/system helper backends BTRC
TPM2 and Secure Boot helpers BTRC with VM capability coverage
Immutability BTRC source compiled by the flake-pinned compiler
Native system tray Implemented through the BTRC stdlib tray backend and packaged as nixosctl-tray
VFIO Removed for now
Python / Rust Removed from the management layer

Maintenance Rules

  1. Prefer settings.* for host policy.
  2. Keep architecture-specific behavior as capability gates, not broad host-level removal.
  3. Keep app installs under settings.apps.*.
  4. Keep QEMU architecture assumptions inside the matching config/hosts/<arch>/QEMU.
  5. Do not add tests that only assert that broken or unimplemented behavior is absent.
  6. Add positive tests for expected behavior.
  7. Run at least the BTRC build and relevant graph node after touching BTRC or VM test code.
  8. Do not reintroduce VFIO until there is a clean design and expected-behavior test path.
  9. Do not remove desktop packages or host customizations while making cross-platform changes unless they are concretely unsupported on that platform.

macOS

The Mac configuration is in mbp21. Its single default.nix contains host package selections, shell overrides, Home Manager configuration and permission intent. config/outputs/hosts.nix selects Darwin for this host, and config/system/darwin holds its platform modules. The standalone Home Manager output reuses the Darwin system's user declaration.

The two platforms pin separately on purpose. nixosctl update --upgrade passes only the inputs whose names do not contain darwin (NixosConfig.linuxInputs reads them out of flake.lock), and the Mac's nix-upgrade alias updates only nixpkgs-darwin, home-manager-darwin and nix-darwin. A bare nix flake update ignores that split and moves both sides at once, so use the scoped commands unless you mean to bump everything.

nix build .#darwinConfigurations.mbp21.system --no-link
sudo darwin-rebuild switch --flake .#mbp21

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages