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 |
Commands marked 馃И are experimental: the idea or implementation is still uncertain and may be removed, replaced, or overhauled before braid v1.0.
| 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 |