Readme

HeyOS — Modular NixOS Dotfiles

Fully hermetic NixOS flake composing 9 hosts from reusable modules. Zero impure dependencies. Built on a “Modular-First” philosophy with a custom Janet CLI (hey) bridging declarative Nix and imperative ops.

Quick Start

hey sync          # rebuild current host
hey check         # validate syntax + flake

Host identity comes from hosts/<name>/ — no --impure, no HEYENV, no environment variables needed at build time.

Deployment Workflows

Scenario	Command	Backend
Rebuild (boot)	`hey sync`	`nixos-rebuild boot`
Rebuild (live)	`hey sync switch`	`nixos-rebuild switch`
Fresh local install	`hey install --host H --root /mnt`	`nixos-install`
Fresh remote install	`hey ops bootstrap H T`	`nixos-anywhere` + `disko`
Remote deploy (safe)	`hey ops deploy H T --boot`	`nixos-rebuild boot --target-host`
Remote deploy (live)	`hey ops deploy H T`	`nixos-rebuild switch --target-host`
Push SSH keys	`hey ops push-keys H T`	`scp` + `ssh-keygen`

nixos-rebuild builds locally and copies closures to the remote — no compilation on low-RAM VPS nodes. --boot only updates the bootloader entry, so a bad deploy can’t lock you out.

Architecture

hosts/<name>/          Per-host composition (9 hosts)
modules/               Reusable feature modules (the core)
lib/                   Nix library + Janet runtime
bin/                   hey CLI (Janet) + shell scripts
config/                Raw dotfiles → linked via home.file
packages/              Local derivations
docs/                  Subsystem documentation

Host Types

Role	Hosts	Description
Workstation	id3-eniac, id3-yoga	Desktop PCs with GPU, multi-monitor
Server	lab-matrix, vps-pacman, vps-ultraman	Gateway, proxy, web services
Portable	bio-alpha, bio-smart	Lab laptops
Board	sbc-opi5p	Orange Pi 5 Plus ARM SBC

Key Principles

Hermetic builds — toString self provides all paths, no impure evaluation
Themes decorate, not define — Catppuccin Mocha baseline, active theme overrides
Impermanence — root erased on boot, user state at /persist
Profile system — hosts compose via role, hardware, networks profiles
Home Manager as file bridge — home.file / home.configFile, no deep nesting

Security

7-layer defense-in-depth, enabled by default:

Layer	Technology
Hardware	YubiKey FIDO2
Boot	Lanzaboote Secure Boot
Disk	LUKS2 + Btrfs subvolumes
Kernel	sysctl hardening, module blacklisting, AppArmor
Secrets	Agenix (age-encrypted, host-key-gated)
Network	Tailscale mesh + Nginx reverse proxy
Apps	nixpak Bubblewrap sandboxing

Kernel attack surface reduction: dccp, sctp, rds, tipc, algif_aead, xfrm_*, esp*, rxrpc blocked via blacklist + install ... /bin/false.

`hey` CLI

hey sync              Rebuild current host (boot)
hey sync switch       Rebuild and activate immediately
hey sync build-vm     Build test VM
hey ops deploy H T    Deploy to remote host
hey ops bootstrap H T Fresh remote install (nixos-anywhere)
hey ops push-keys H T Provision SSH keys before bootstrap
hey check             Validate syntax + flake
hey pull              Update flake inputs
hey gc                Garbage collection
hey .<script>         Execute bin/ script (WM-aware)

16 Janet subcommands in bin/hey.d/. Built on defcmd macro with automatic option parsing. WM-agnostic scripts in bin/; WM overrides in config/$WM/.

Development Loop

# 1. Edit files
vim modules/shell/git.nix

# 2. Check syntax
hey check syntax

# 3. Rebuild (boot — activates on next reboot)
hey sync

# 4. Verify
hey check eval          # user must run this (may hang on recursion)

# For Janet/hey changes only:
./scripts/build_hey.zsh  # instant test, no rebuild needed

Credits

Forked from Henrik Lissner’s dotfiles — the “Dotfiles as a Framework” philosophy and core hey toolchain.

Neovim: AstroNvim v6 + lazy.nvim, inspired by Mic92.

App sandboxing: nixpak, adapted from ryan4yin.