Immutable Architecture

Nitrux has used an immutable root filesystem since version 2.6.0 (January 2023); this change lets us provide new distribution versions with greater certainty that root modifications won’t cause conflicts. It also prevents issues caused by traditional package managers installing or upgrading packages from third-party sources we cannot control, which conflict with Nitrux’s immutable architecture and our intended system configuration. NX Overlayroot implements this with OverlayFS, a union filesystem that presents a unified view by overlaying a writable layer on a read-only base. Changes appear to persist during a session but do not alter the underlying root.

Why Immutability Matters?

1. System integrity and certainty. The immutable root guarantees the base system remains in a known state. No package upgrade, user error, or malware can silently alter core system files. When troubleshooting, the root is never the variable—eliminating an entire class of unknowns.
2. Reproducible updates. Immutability enables the OTA-style update model used by the Nitrux Update Tool System (NUTS).
3. Validation of software philosophy. Software installation occurs entirely outside the immutable root, using AppBoxes (stored in user space), Flatpaks, and Distrobox containers.

Architecture Diagram

This diagram shows the separation between the immutable base, the ephemeral overlay, and persistent user data.

                 USER-VISIBLE MOUNT NAMESPACE
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  /  ──────────────── Merged OverlayFS view                  │
│  │                                                          │
│  ├── /home ───────── Separate persistent filesystem         │
│  │                                                          │
│  └── /var/lib ────── Separate persistent filesystem         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                │               │                │
                │               │                │
        ┌───────▼───────┐ ┌─────▼─────┐ ┌────────▼────────┐
        │  OverlayFS    │ │ NX_HOME   │ │   NX_VAR_LIB    │
        │  mounted at / │ │  F2FS     │ │      F2FS       │
        └───────┬───────┘ └───────────┘ └─────────────────┘
                │
        ┌───────┴────────┐
        │                │
┌───────▼────────┐ ┌─────▼────────────┐
│ Upper layer    │ │ Lower layer      │
│ tmpfs          │ │ NX_ROOT          │
│ Ephemeral      │ │ XFS              │
│ Discarded      │ │ Persistent       │
│ on reboot      │ │ Read-only via /  │
└────────────────┘ └──────────────────┘
                │                 │
                └────────┬────────┘
                         ▼
              RECOMMENDED STORAGE LAYOUT

                 NX_ROOT  → /
                 NX_HOME  → /home
                 NX_VAR_LIB → /var/lib
                 ESP      → /boot/efi
                 SWAP     → swap

Persistent Writable Locations

While the root filesystem is immutable during normal operation, persistent writable data remains outside the overlay:

• /home → User home directories and personal data.
• /var/lib → Persistent system and service state.

/var/lib stores data required by services and runtimes across reboots. NetworkManager stores connection profiles there instead of /etc; BlueZ stores paired Bluetooth devices there; Flatpak uses it for system-wide installations; and rootful Distrobox containers store their data there.

Administrative Workflow

Administrative modifications to the root require either overlayroot-chroot or temporarily disabling the overlay. overlayroot-chroot is the preferred method; disabling the overlay is intended primarily for debugging.

Information

For detailed information on NX Overlayroot, see System Management → System Administration → NX Overlayroot.

For detailed information on the Nitrux Update Tool System, see System Management → System Administration → Nitrux Update Tool System.