headless

For setting up, updating or checking a machine normally reached only over SSH. Mac uses Determinate Nix and nix-darwin; Linux uses a NixOS module or distro-neutral scripts for Debian, Ubuntu and Fedora; Windows uses a PowerShell configuration. Replacing another Linux installation with NixOS is an optional, destructive branch, not a prerequisite.

Use a macOS or Linux controller with bash, ssh and tar. Controller-side Nix is needed only for the optional NixOS reinstall. The target needs a reachable address, SSH, an administrator account with a password, and your SSH key. Supported targets are Apple silicon on current macOS, systemd Linux on x86_64/aarch64, and Windows 11 or Server 2025 on x86_64/Arm64. Windows requires a local administrator, not a Microsoft account; its account name cannot contain spaces and is limited to 20 characters, while the hostname is limited to 15. The user saves the password in a secret store and supplies its reference, not the password itself. The workflow handles its documented platform setup; those installation steps are not extra work the user must finish first.

Provide the target address, administrator account and secret-store entry reference, then choose the machine name, local configuration directory and options. The README gives this starting request:

/headless set up my Mac mini at 192.168.1.20 as a headless machine

The workflow creates a local Git configuration folder, by default ~/headless/<machine-name>, pins the SSH host key and proves key access before disabling password sign-in. It then applies the selected platform configuration, reads settings back, announces the restart and checks the machine again afterward. Automatic sign-in and platform extras default on; Tailscale defaults off. Linux automatic sign-in starts user services at boot rather than a desktop session. Tailscale enrollment, if chosen, uses a user-approved sign-in link or a secret-store auth-key reference. The local Git folder is not automatically pushed to a remote.

Mac automatic sign-in turns FileVault off and stores a root-recoverable password in /etc/kcpassword. With autoLogin: false, FileVault can remain on, but its unlock screen limits unattended access after restart. Windows stores automatic-sign-in credentials as an LSA secret that administrators can still recover. The documented secret-store/pipe design is not a demonstrated guarantee that a privileged agent cannot access secrets; the fallback env file is plaintext and readable by processes with the user's shell permissions.

This changes remote system settings and copies scripts/configuration to the target. Windows administrator SSH sessions are already elevated, and machine.ps1 runs with that authority on each apply. Optional NixOS installation erases the chosen whole disk; applying on NixOS replaces /etc/nixos, initially backing it up to /etc/nixos.before-headless, and later edits there can be overwritten. Copied NixOS configuration may contain private material, so inspect it before sharing or pushing the local folder. Turning Mac/Windows extras off does not restore their old values; Linux keeps masked sleep targets and installed packages.

Software setup may download dependencies, and optional Tailscale contacts a tailnet control service; Headscale can be selected instead. A changed SSH host key stops the documented workflow for review. The source's password-handling and platform-test claims are documentation, not results reproduced here.