NaxOS Management Daemon & API (naxos-api)
The NaxOS Management Daemon serves as the core orchestration brain of the NaxOS storage appliance. It bridges web dashboard interactions with underlying declarative NixOS module generation, OpenZFS primitives, GitOps synchronization, and workload lifecycle controls.
Core Capabilities
- Declarative NixOS Compiler: Translates REST API actions directly into standard NixOS module syntax (
generated-naxos-config.nix), validated before activating vianixos-rebuild switch. - GitOps Synchronization Engine: Every configuration modification creates an atomic local Git commit and automatically pushes to the remote repository (e.g. Gitea) with instant 1-click rollback capability.
- Native OpenZFS Management: Full REST API for pools, vdevs, datasets, quotas, snapshots, scrubs, and TRIM.
- Foreign Pool Migration: Zero-data-loss safe discovery and import of foreign ZFS pools from TrueNAS or raw NixOS setups like
nixos-lukas. - Tri-Tier Workload Engine: Manages native NixOS systemd services (e.g., Immich with Intel QuickSync / OpenCL hardware acceleration), rootless Docker Compose, and lightweight K3s clusters.
- Native Perses Analytics & SSE Logs: Serves embedded Perses dashboard configurations and streams real-time journald logs.
REST API Overview
| Endpoint | Method | Description |
|---|---|---|
/api/v1/system/status |
GET |
Appliance health, CPU, RAM, ARC hit ratio |
/api/v1/system/rebuild |
POST |
Triggers declarative rebuild; streams output via SSE |
/api/v1/storage/pools |
GET, POST |
List and create ZFS pools |
/api/v1/storage/unimported |
GET |
Scan for unimported foreign pools |
/api/v1/storage/import |
POST |
Safely import foreign pool without data loss |
/api/v1/storage/datasets |
GET, POST |
Manage ZFS datasets, quotas, recordsize |
/api/v1/storage/snapshots |
GET, POST |
Snapshot creation and instant rollback |
/api/v1/shares/smb |
GET, POST |
Samba shares and Time Machine configurations |
/api/v1/shares/nfs |
GET, POST |
NFS exports and CIDR rules |
/api/v1/apps/catalog |
GET |
Catalog of deployable applications |
/api/v1/apps/installed |
GET, POST |
Install and manage active app workloads |
/api/v1/gitops/status |
GET |
Remote synchronization and commit state |
/api/v1/gitops/rollback |
POST |
Instant rollback to arbitrary commit SHA |
/api/v1/logs/stream |
GET |
Real-time Server-Sent Events journald stream |
Development & Testing
npm install
npm test
npm run build
npm start