braid is a NixOS CLI tool for managing an encrypted btrfs RAID1 NAS. These docs cover end-user workflows, command reference, design decisions, internals, and development practices.
Guide Description
Install NixOS Install NixOS itself before setting up braid Getting started First-time setup: find disks, create pool, unlock Day-to-day NAS usage Subvolumes, file permissions, Samba shares Auto-unlock USB keyfile setup for unattended reboots Monitoring and alerts Disk health alerts, beeper, alert commands Power management Auto-suspend, Wake-on-LAN, RTC wakeups Fan control HDD-driven chassis fan control, SATA hotswap UPS NUT-backed orderly poweroff, preflight safety, live status NixOS configuration Module options, scrub scheduling, pinned toolchain Sharing and permissions Storage group, mount permissions, Samba Mounting subvolumes Expose a btrfs subvolume at a custom path Troubleshooting ENOSPC balance, paused balance, missing devices Recovery scenarios Interrupted operations, lost pool.json, degraded mount
Command Description
add Add disks to the pool or create a new pool remove Remove a live disk from the pool remove-missing Forget a dead or missing device entry replace Replace a live or dead disk unlock Open LUKS devices and mount the pool lock Unmount the pool and close LUKS devices seal-mountpoint Seal the offline mountpoint immutable (boot-managed) idle Check if the pool is idle for auto-suspend status Pool health, disk status, allocation, scrub info doctor Diagnostic checks for config and pool health monitor Health check for alerting used by systemd timer ack Acknowledge and silence an active alert enroll Enroll a USB keyfile for auto-unlock discover Scan for braid LUKS devices and rebuild pool.json recover Recover from an interrupted operation tui Interactive dashboard with raw-output Browse tab ups status Live UPS state from NUT, with JSON for scripts
Doc Purpose
Overview Development workflow and dependency updates Testing VM test conventions and framework gotchas TUI snapshots Ratatui and Insta snapshot review workflow