NaxOS Documentation

Comprehensive Technical Architecture & Operations Guide (NixOS 26.05 & OpenZFS)
Architecture Specifications, API Reference, Migration Runbooks, and Bare-Metal Guides

---

Welcome to the comprehensive documentation repository for NaxOS, the declarative, appliance-like Network Attached Storage (NAS) operating system built on NixOS 26.05 and OpenZFS.

---

Visual Tour & Web Dashboard Showcase

1. Dashboard Overview

Sleek glassmorphism interface featuring circular storage capacity gauges, real-time ZFS ARC cache telemetry, active workloads, and safe declarative system rebuild triggers.

2. OpenZFS Storage Management

Declarative OpenZFS pool topology browser, dataset quota manager, snapshot timeline rollback, and pool health monitoring.

3. Foreign Pool Migration Wizard

Zero-data-loss Appliance Setup & Migration Wizard safely detecting and importing foreign pools from TrueNAS or nixos-lukas while preserving Immich photo libraries in tank/media/photos.

4. Seamless Integrated Real-Time Telemetry

Embedded live telemetry replacing standalone Grafana for real-time ZFS ARC hit ratios (98.6%), storage pool I/O bandwidth, multi-core CPU load, and dynamic RAM footprint directly woven into the appliance interface.

5. App Store & Tri-Tier Workload Runtime Engine

Curated 1-click self-hosted application catalog with hardware-accelerated Immich (Intel QuickSync QSV / OpenCL), Nextcloud, Jellyfin, and Vaultwarden. Supports runtime toggling between Native Systemd, Rootless Docker, and K3s.

---

Table of Contents

1. Architecture & Internals

• High-Level Architecture & Philosophy
• Declarative Backend & GitOps Engine
• OpenZFS Storage Engine & Pool Migration
• Workload App Engine & Tri-Tier Runtimes
• CNCF Perses Native Observability

2. User & Administrator Guides

• Installation & Live ISO Guide
• Testing NaxOS on macOS (QEMU & Local)
• Migration Guide: Transitioning from nixos-lukas to NaxOS

3. Developer Manual

• Management Daemon REST & WebSocket API Reference
• Contributing & Development Workflow

---

Ecosystem Repositories (naxos Organization)

Repository	Description	Gitea URL
naxos-os	Core NixOS distribution, declarative modules, Flake, and ISO builder	git.lholz.de/naxos/naxos-os
naxos-api	Management Daemon, REST/WebSocket API, GitOps synchronization, ZFS engine	git.lholz.de/naxos/naxos-api
naxos-ui	Modern web dashboard, embedded Perses metrics, pool manager, app store	git.lholz.de/naxos/naxos-ui
naxos-docs	System architecture, migration tutorials, developer guides, and API specs	git.lholz.de/naxos/naxos-docs