Hosts and homes · Commands · Checks · Runbooks

A Nix flake for William's NixOS workstations and NAS, a headless macOS node, and Home Manager environments. System configuration and user configuration are separate outputs; selecting the right home matters as much as selecting the right host.

• Another user's machine: start with the public Home Manager installer, not a named owner configuration.
• William's existing machines: choose the host below, then follow NixOS host operations or headless macOS operations.

Architecture

flake.nix composes two platforms: x86_64-linux and aarch64-darwin.

flake.nix
├── programs/                    Owned C/Rust source, packages and local checks
├── system/
│   ├── modules/base.nix          Shared NixOS foundation
│   ├── modules/workstation.nix   Base + graphical services
│   ├── modules/server.nix        Base + headless assertions
│   ├── <host>/                   NixOS hardware, storage and services
│   └── darwin/                   Relay's nix-darwin system services
└── home/
    ├── default.nix               Home Manager entry point and identity defaults
    ├── private.nix               Owner secret groups and agent-bus integration
    ├── user/                     Packages, programs, shell and service modules
    └── config/                   Managed configuration, scripts and LLM harness

Owned utilities and services live in programs/, with their package definitions beside the source. Static configuration remains in home/config; Home Manager and system modules choose how programs are deployed.

System and home boundaries

• NixOS: all four hosts inherit base.nix, including boot, locale, Nix, the William account, Fish, NetworkManager, OpenSSH and Tailscale. The workstation role adds Hyprland, audio, printing, Bluetooth and Docker. The server role omits that layer and asserts that the display manager, X server and graphical boot remain disabled.
• macOS: system/darwin/ manages headless system jobs through nix-darwin. Home Manager supplies their user configuration. Relay's system pins its matching home generation, so changes must deploy as a pair. This is not a macOS installer.
• Home Manager: home/user/default.nix composes the user modules. capabilities.nix assigns workstation, automation, nas or legacy roles, controlling packages, integrations and services separately from hardware configuration.
• Public/private: public homes include the shared modules without owner integrations. Owner homes additionally import the private nix-config and agent-bus inputs and home/private.nix. Named owner systems and homes require authenticated input access; they are not portable installation defaults. Keep credentials out of Nix expressions and the store.

Other flake outputs

• lib.mkHome constructs a home for a supplied identity and is public by default. homeModules.default exposes the public module composition for reuse. See public installation and reuse.
• overlays.default supplies the repository's tool packages and selected overrides to NixOS and Home Manager. It is distinct from the exported packages set.
• packages.<system> exposes runtime adapters/helpers, activation-dbus, private-access-probe, mcp-dap-server and content-addressed theme-* fetches. No apps output or automated test checks are declared.
• formatter.<system> uses treefmt. devShells.<system>.default supplies development tools and installs formatting, syntax and secret-protection hooks, not test runners. These per-platform outputs are wired under perSystem in flake.nix.

Hosts and roles

NixOS system attributes below live under nixosConfigurations; Relay lives under darwinConfigurations. Home attributes live under homeConfigurations.

Host / system attribute	Machine and system role	Home attribute / role
andromeda	Thelio Major Threadripper workstation; System76 support and NVIDIA RTX 5090 configuration	william@andromeda workstation
starfish	Dell Precision 5750 workstation; host-specific hardware and filesystem configuration	william@starfish legacy
foundation	Framework 13 AMD AI-300 workstation; nixos-hardware support	william@foundation workstation
terminus	Beelink headless NAS; ZFS media storage, Immich, Audiobookshelf and Pi Switchboard hub	william@terminus nas
relay	Apple Silicon headless macOS automation node	william@relay automation

legacy preserves the full workstation capabilities for Starfish and generic Linux homes. Terminus excludes desktop configuration and work integrations while retaining maintenance and NAS tools. Relay uses headless browser automation rather than the workstation desktop profile.

Terminus receives immichPkgs from the locked unstable input for Immich; its main package set remains on the release input. Foundation receives nixos-hardware through its host special arguments. Host-specific services and hardware live in system/; do not substitute another host's configuration.

Homes without a host-qualified name

Home attribute	Intended use
laptop	Public reference identity, not the current user. The installer supplies the actual username, home and checkout paths.
william-linux	Generic owner Linux home, with the legacy role.
william	Alias of william-linux, not automatic platform detection. Avoid it on macOS.
william-darwin	Alias of Relay's automation home, not a generic macOS desktop profile.

What to run

Public Home Manager installation

Use an existing normal account with Git, Bash and working Nix. The isolated installation test targets x86_64 Linux. This installs user configuration, not NixOS, disks, graphics drivers or system services. Review the prerequisites and recovery notes before adopting it over a customised home.

git clone https://github.com/willfish/nix.git ~/.dotfiles
cd ~/.dotfiles
bash scripts/install-home --public --dry  # Build only; skip private-access detection

Activation changes the current user's managed files and settings. Run without sudo:

bash scripts/install-home --public

Without --public, the installer enables private composition only after SSH-derived secret decryption and access to the required private inputs succeed. After installation, hmswitch remembers the checkout location. Pi needs the new user's own provider credentials.

Build an owner configuration without activation

Run from this checkout in its dev environment, using direnv exec . as below or an already active nix develop shell. Owner commands require private input access. Build on the target platform or a suitable native builder.

# NixOS: replace foundation with the selected NixOS host from the table.
direnv exec . nix build --no-link .#nixosConfigurations.foundation.config.system.build.toplevel

# Home Manager: choose the host-qualified home, especially for Terminus.
direnv exec . nix build --no-link '.#homeConfigurations."william@foundation".activationPackage'

# Relay: run on native macOS; the system pins its matching home generation.
direnv exec . nix build --no-link .#darwinConfigurations.relay.system

Activate an existing owner host

Warning

These commands change the running host or home. Build first and follow the relevant runbook's preflight and recovery steps.

On the selected NixOS host, from this checkout:

nh os test .    # Activate temporarily, without changing the boot default
nh os switch .  # Make the system generation persistent, after smoke checks

For Home Manager, prefer the installed wrapper:

hmswitch

It selects a known Linux host's william@<host> home, falling back to william-linux. On Relay after the initial handover, it builds and deploys the matching Darwin system before activating that system's exact home generation; sudo may prompt. Use headless macOS operations for first handover, native SSH access and recovery. hmswitch --dry previews the Relay pair without activation.

If invoking nh directly on Linux, pass the flake path and configuration separately, for example nh home switch . --configuration william@foundation. Do not use nh home switch '.#william-darwin', or bypass Relay's paired deployment with a standalone home switch.

For routine read-only health reports, Justfile provides just health for reachable known hosts and just health terminus for one host. just terminus-health adds detailed ZFS/SMART checks and may prompt for sudo.

Checks and maintenance

There is no CI workflow in this checkout. Local commit hooks are not host builds, and pushes do not build NixOS or Home Manager configurations.

Use direnv exec . nix fmt -- --ci for formatting, then build and verify the affected package or host. There is no repository-wide test suite or flake test gate. Optional migration fixtures live inside their program directories and run manually, not during builds or commits. Follow host operations for deployment checks and public-install.md for the public installation boundary.

Follow AGENTS.md when changing this repository: do not create branches unless explicitly instructed, and fast-forward any authorized branch into master before pushing. Build, activate and verify affected configurations before committing module changes, subject to authorization. Use hmswitch for home activation.

Where to go next

Task	Documentation
Install or reuse the public home	Public install
Build, activate, roll back or check NixOS and Terminus services	NixOS host operations
Provision or operate Relay's paired system and home	Headless macOS
Configure the desktop, login or recovery	Hyprland
Reproduce screen recording with camera overlay elsewhere	hypr-record
Change shared themes and fonts	Appearance
Use Pi's coding workflow	Pi workflow
Configure Pi's MCP integration	Pi MCP
Operate local models	Local LLM
Change a C helper	C programs
Refresh or re-serve the radio archive on Terminus	Radio archive

Shared agent rules, guides and skills live under home/config/llm/; home/user/llm-harness.nix wires their deployment. Edit maintained source rather than generated files in the home directory.