Skip to content

README.md

Latest commit

 

History

History
1683 lines (1347 loc) · 139 KB

README.md

File metadata and controls

1683 lines (1347 loc) · 139 KB
Raw

NEURONIX OS Official Banner

License Release Version NixOS Architecture Testing Filesystem Memory CI/CD Verification Passport RFC 8785 JCS Conformance

NEURONIX OS: The Self Healing, Declarative Workstation for Mission Critical Engineering & Local AI Development
Dual-Plane Micro-Engine • Cryptographic Generational Immutability • Ephemeral Blast Radius Containment • NIP RFC Governance

BUILD Mathematically Reproducible Flakes • CONTAIN Ephemeral Workspaces • RECOVER Autonomous Zero Loss Generations

Table of Contents

Overview

NEURONIX OS is an independent, declarative Linux distribution platform based on NixOS. It provides an automated Calamares installation workflow, pre configured hardware and kernel profiles, transactional desktop environments, and developer CLI utilities while maintaining full compatibility with the upstream Nix package ecosystem.

Release Engineering & Version Truth

  • Single Source of Truth (version.nix): All components (CLI, GUI Center, MCP Daemon, Calamares installer engine, release manifests, package derivations) read canonical versioning from version.nix.
  • Release v1.0.0 (Frozen GA): Immutable initial General Availability release tag.
  • Release v1.0.4 (Hardened Milestone): Production hardening baseline establishing closed semantic subsystems and offline verification passports.
  • Release v1.0.5 (Hardened Production Baseline on main): Actively maintained release incorporating modular CLI architecture (src/lib/ and src/commands/) with verified flock concurrency locking, 100% static Python type annotation coverage (302/302 functions across 21 core files), 100% Rust documentation comments (29/29 public items across conductor and neuronix-daemon crates), RFC 8032 pure Python Ed25519 known-answer test vectors, property-based invariant testing, comprehensive mutation resilience (100% kill rate across 10 mutants), hardened architecture aware OCI container security profiles (standard userspace seccomp allowlist under fail-closed SCMP_ACT_ERRNO, noNewPrivileges, capability bounding, unprivileged namespaces), dynamic version-bound evidence compilation, and end-to-end hardware contract validation (1,384 assertions).
  • Development Channel Baseline: Tracks nixos-unstable for modern Linux kernels, Wayland compositors, and rapid developer tooling.
  • Production Stable Baseline: Targets nixos-26.05 for conservative enterprise stability and verified patch streams.
  • State Version (system.stateVersion = "24.11"): The immutable NixOS state migration baseline preserving data directory layouts and system state compatibility across upgrades.

Primary Purpose, Target Audience & Operational Scenarios

Design Objectives & Core Utility

NEURONIX OS is engineered to resolve fundamental operational vulnerabilities common to traditional Linux distributions: configuration drift, dependency breakage during upgrades, lack of system state reproducibility, and fragile disaster recovery. Built on a pure-functional NixOS substrate, NEURONIX OS elevates declarative configuration from a specialized sysadmin toolkit into an enterprise-ready, desktop grade operating platform.

Its primary design objectives are:

  1. Deterministic State Reproducibility: Every package derivation, system daemon, kernel option, and configuration parameter is declared as pure code within flake.nix and pinned cryptographically via flake.lock. Deploying a configuration across multiple physical or virtual nodes produces mathematically identical systems, eliminating divergent package closures and unrecorded host mutations.

  2. Atomic Generational Lifecycle with Zero Loss Rollback: Operating system upgrades and package modifications are compiled and staged into isolated cryptographic store paths (/nix/store) before system symlink pointers are switched atomically. The running operating system is never modified in place. If an update introduces regressions or unbootable states, users and automated recovery services can revert to the previous operational generation instantly at the bootloader or from the active shell (nixos-rebuild --rollback or neuronix-rollback) without data loss.

  3. Turnkey Desktop Ergonomics on an Immutable Foundation: Functional package managers historically impose steep friction for desktop users. NEURONIX OS bridges this divide by providing a declarative Calamares installer engine, automated hardware profile detection, out of the box global FHS binary execution via nix-ld (enabling unpatched execution of VS Code, proprietary CLI tools, and CUDA binaries), and a dual-layer application model pairing immutable core system derivations with user-managed Flathub Flatpaks.

  4. Autonomous Reliability & Local AI Developer Substrate: Modern workstations require active telemetry and intelligent maintenance. NEURONIX integrates memory pressure defenses (ZRAM ZSTD compression paired with Pressure Stall Information monitoring via systemd-oomd), background storage hygiene (automated TRIM, metadata balancing, and store deduplication), and an embedded OpenCode AI copilot coupled with a standardized Model Context Protocol (MCP) JSON-RPC 2.0 interface.

Intended Audience & Professional Roles

NEURONIX OS is purpose built for technical professionals and organizations requiring uncompromising system predictability, security isolation, and developer agility:

  • Systems Engineers & Site Reliability Engineers (SREs): Engineers who treat infrastructure as code. NEURONIX provides a workstation environment that mirrors modern cloud native deployment patterns, enabling local testing of complex declarative environments that compile directly to production-grade server appliances without environmental discrepancies.

  • AI & Machine Learning Researchers: Practitioners requiring isolated, reproducible compute stacks. The neuronix dev ai substrate provides immediate access to PyTorch, CUDA runtime libraries, JupyterLab, and Ollama without polluting system libraries or conflicting with host NVIDIA display drivers.

  • Security Analysts & Penetration Testers: Specialists requiring auditable environments with minimal attack surfaces. NEURONIX supports hardened kernel branches (linuxPackages_hardened), cryptographically sealed package closures, ephemeral in memory micro VM evaluation (neuronix sandbox), and isolated execution sandboxes (neuronix run --sandbox).

  • Full-Stack & Cloud-Native Developers: Engineers working across polyglot stacks (Rust, Go, Python, TypeScript, Node.js). NEURONIX eliminates global package version conflicts through instant project level development shells (neuronix dev <stack>), while nix-ld enables direct execution of standard pre compiled dynamic ELF binaries.

  • Production Workstation Operators: Users who depend on daily system availability. Traditional rolling release systems risk catastrophic breakage during routine updates; NEURONIX delivers modern packages (Linux Zen kernel, Wayland compositors, modern desktop environments) backed by deterministic boot time rollback to previous working generations.

Optimal Use Cases & Deployment Profiles

  • Mission-Critical Engineering Workstations: Primary daily driver operating system for engineering organizations where workstation downtime equates to lost development velocity. Routine updates occur without fear of library incompatibilities, and complete disaster recovery requires seconds rather than system reinstallation.

  • Autonomous Edge & Local AI Inference Nodes: Dedicated local hardware running persistent background reasoning models, autonomous code agents, and automated data pipelines via the OpenCode background daemon and MCP JSON-RPC protocol transport.

  • Hermetic Build & Clean-Room Verification Environments: Building and verifying software packages in pure, isolated sandboxes where external host state, ambient environment variables, and unpinned network dependencies are strictly blocked from influencing compilation outputs.

  • Rapid Hardware Qualification & Benchmarking: Validating modern PC and laptop hardware across distinct performance profiles. Switching between low latency scheduling (zen), conservative enterprise stability (lts), or attack-surface hardened (hardened) kernels requires modifying a single declarative configuration attribute.

Architectural Comparison: Head-to-Head Matrix

Scope & Evaluation Baseline

To evaluate NEURONIX OS objectively, it is compared directly against leading operating systems occupying equivalent architectural niches:

  1. Vanilla NixOS: Upstream pure-functional parent platform.
  2. Fedora Silverblue / Atomic Desktops: Modern enterprise-backed immutable OSTree image platform.
  3. openSUSE MicroOS / Aeon: Transactional snapshot-based rolling distribution using Btrfs and Snapper.
  4. EndeavourOS / Arch Linux: Mainstream bleeding-edge rolling release distribution for software developers.

Comparative Feature & Architecture Matrix

Architectural Dimension NEURONIX OS (v1.0.5) Vanilla NixOS (24.11/Unstable) Fedora Silverblue (Atomic) openSUSE MicroOS / Aeon EndeavourOS / Arch Linux
System Paradigm Pure-functional declarative substrate Functional declarative toolkit Image-based OSTree composition Transactional Btrfs snapshots Imperative mutable Unix filesystem
Configuration Model Single declarative Flake (flake.nix) Declarative Nix expressions or channels Imperative package layering (rpm-ostree) Imperative packages via transactional-update Imperative commands (pacman, Arch build system)
Store Immutability Cryptographic read-only /nix/store Cryptographic read-only /nix/store Read-only /usr deployment tree Read-only root filesystem snapshot Fully mutable root and /usr trees
Upgrade & Rollback Mechanism Atomic live symlink switch; instant zero-loss rollback Atomic live symlink switch; instant boot generation rollback OSTree deployment switch; requires reboot to activate Btrfs root snapshot switch; requires reboot to activate In-place library overwrites; manual chroot or snapshot recovery
Out-of-the-Box GUI Installer Calamares GUI generating pure Nix Flakes Minimal text installer; Calamares without flake generation Anaconda graphical installer Agama / YaST automated installer Calamares graphical installer
Hardware Detection Architecture Declarative 27-pillar matrix; offline firmware; PRIME offload Manual hardware-configuration.nix; user-configured drivers Automated via Anaconda; layered driver packages Automated via YaST hardware database User-managed via Arch Wiki and Pacman
Kernel Tiering Support Declarative switch: zen, lts, hardened, default Manual Nixpkgs package overrides Stock Fedora kernel; manual kmods Stock openSUSE kernel; rolling branch Manual Pacman kernel packages
Memory Pressure Shield ZRAM Zstandard pool + PSI monitoring + systemd-oomd Manual zram-generator and service configuration Stock systemd-oomd; standard swap Stock systemd-oomd; zram configuration Manual setup (earlyoom, systemd-swap)
FHS Dynamic Binary Compatibility Pre-configured nix-ld for VS Code, CUDA, and ELFs Requires manual nix-ld or steam-run wrapping Handled via Toolbox / Distrobox containers Handled via Distrobox containers Native POSIX/FHS directory hierarchy
AI Copilot & Telemetry Daemon Native OpenCode daemon + MCP JSON-RPC 2.0 server None (user-installed applications only) None (user-installed applications only) None (user-installed applications only) None (user-installed applications only)
Storage Topology & Compression 5 Btrfs subvolumes (@, @home, @nix, @snapshots, @swap) + ZSTD:3 User-defined partitioning (defaults to monolithic) Btrfs root with subvolumes; no transparent compression Btrfs root with Snapper read-only subvolumes Monolithic Btrfs or EXT4 without subvolume convention
Automated Assurance Gate 1,384 verified assertions across 32 QA suites, distro harness, and 25 standalone gates (100% Pass) Hydra continuous integration build checks Fedora Zuul CI / openQA test suites openQA automated validation matrix User community testing repository
Release Provenance Pinned Flake commit + RFC SHA-256 + SPDX 2.3 SBOM Hydra output provenance Koji build logs / RPM signatures OBS build provenance Arch build system logs

In Depth Architectural Differentiators

1. NEURONIX OS vs. Vanilla NixOS

Vanilla NixOS provides an exceptional functional package management paradigm, but operates fundamentally as an infrastructure toolkit rather than a cohesive, out of the box desktop distribution. A user installing vanilla NixOS must manually architect their Btrfs subvolume layout, configure swap parameters, script hardware driver integrations (such as NVIDIA PRIME offloading), research dynamic linker workarounds for proprietary software (nix-ld), and resolve complex multi-desktop configurations.

NEURONIX OS transforms this substrate into an engineered, production ready distribution. It ships with a customized Calamares installation engine that generates production grade Nix Flakes directly from graphical user inputs, provisions an opinionated 5 subvolume Btrfs topology with transparent ZSTD:3 compression, pre-configures memory defenses (ZRAM + PSI telemetry), enables seamless FHS binary execution, embeds local AI copilot services via MCP, and validates every build against a 1,384-assertion test taxonomy (cataloged in data/test_manifest.json). Crucially, NEURONIX achieves this without forking upstream Nixpkgs, ensuring zero security patch latency.

2. NEURONIX OS vs. Fedora Silverblue / Atomic Desktops

Fedora Silverblue enforces immutability by composing system states as read-only OSTree commits. While effective at preventing host corruption, Silverblue introduces significant operational overhead:

  • Modifying layered packages requires invoking rpm-ostree install followed by a mandatory system reboot to switch deployment targets. In contrast, NEURONIX updates packages and system configurations live at runtime via atomic symlink activation (nixos-rebuild switch) without requiring reboots.
  • Silverblue relies on container layers (Toolbox or Distrobox) for everyday development, separating developer toolchains from the host desktop. NEURONIX integrates hermetic development environments natively through Nix Flakes (neuronix dev <stack>), allowing development shells to interact directly with host hardware accelerators and graphics pipelines.
  • Rollbacks in NEURONIX preserve arbitrary past generations indefinitely until explicitly garbage-collected, whereas OSTree typically retains only the immediate previous deployment pin.

3. NEURONIX OS vs. openSUSE MicroOS / Aeon

openSUSE MicroOS and Aeon achieve system resilience by mounting the root partition as a read-only Btrfs snapshot and performing atomic transactional updates via transactional-update and Snapper. While this safeguards against interrupted update writes, the underlying package manager remains imperative. Two systems installed with the same package manifests at different times can yield divergent states due to repository state shifts.

NEURONIX OS couples filesystem resilience with mathematical reproducibility. System state is defined as pure functional derivations locked to cryptographic commit hashes via flake.lock. Furthermore, NEURONIX separates the immutable Nix store (@nix) from user data (@home) and snapshot storage (@snapshots), ensuring that rolling back system generations never impacts user documents, browser profiles, or container state.

4. NEURONIX OS vs. EndeavourOS / Arch Linux

EndeavourOS provides an accessible Calamares installer on top of Arch Linux, earning widespread popularity among software developers seeking rolling-edge packages. However, Arch Linux adheres to an imperative, mutable filesystem model. System upgrades modify shared dynamic libraries (.so files) in-place on the live root partition. If an upgrade is interrupted or introduces broken dependency chains, the host can become unbootable, requiring manual recovery via arch-chroot from a live USB.

NEURONIX OS matches the desktop convenience and performance of EndeavourOS (graphical Calamares setup, first-boot Welcome Hub, Zen kernel scheduling, cutting-edge Wayland desktops) while entirely eliminating mutable dependency fragility. In NEURONIX, new package closures are downloaded and verified in isolation before being linked into the active generation. If any component fails, the previous working generation remains untouched and can be selected instantly from the bootloader menu.

Proof Class Taxonomy (P0 through P4)

To ensure empirical truthfulness and eliminate ambiguous claims, all capabilities in NEURONIX OS are governed by five formal proof classes:

Proof Class Rigor Level & Scope Verification Grounding Subsystems & Features
P0: Mathematical Determinism Functional derivations, bit-identical store paths, pinned inputs. Verified via Nix derivation graph, flake.lock pinned commit, and RFC SHA-256 digests. Pure Nix substrate, pinned Nixpkgs closures, RFC 8785 Merkle StateRoot, Merkle Domain Proofs (MDP), reproducible ISO builds, release manifest hashes.
P1: Automated CI Verification System regression suites, multi-architecture evaluations, micro-VM boots. Validated through 1,384 automated test assertions across 32 QA suites, 19 distro component suites, and 25 lifecycle gates. Multi-arch evaluation, Shadow VM lifecycle, Calamares flake generation, CLI argument fuzzing, MCP JSON-RPC, Provable State & Hyperion Engine, Semantic Closure Gate, Conductor Native Surface & Zero-Idle Runtime, Vital Observation Substrate.
P2: Qualified Reference Hardware Empirical hardware validation on representative bare-metal systems. Validated across 8 reference platforms (ThinkPad, Framework, AMD/Intel workstations, XPS, Zephyrus, Apple Silicon). Intel/AMD microcode, Mesa RADV, Intel Arc Xe, NVIDIA PRIME offload, S3/s2idle power management, PipeWire HD audio.
P3: Declarative Module Support Composable NixOS configuration modules and subsystem policies. 27 hardware configuration pillars managed in modules/hardware/ and data/hardware_qualification.json. ZRAM ZSTD swap, systemd-oomd memory monitor, Btrfs subvolumes (@, @home, @nix, @log, @snapshots), auto-TRIM.
P4: Experimental / Community Optional hardware features, custom Wayland compositor rules, community packages. Documented with operational caveats and manual verification steps in operational runbooks. Lanzaboote UEFI Secure Boot signing chain, TPM2 LUKS auto-unlocking, custom Hyprland animations.

Platform Architecture

flowchart TD
    subgraph L1["Layer 1: User Experience (UX)"]
        CAL(["Calamares Declarative Installer"]):::ux
        CTR["NEURONIX Center GUI & Telemetry"]:::ux
        DE["KDE Plasma 6 / GNOME / Hyprland"]:::ux
        SW["Dual-Layer Software (Nix Core + Flatpak)"]:::ux
    end

    subgraph L2["Layer 2: Desktop & System Core"]
        NIX[("Pure Nix Substrate (/nix/store)")]:::core
        HW["Hardware Hardening & Compatibility Matrix"]:::core
        NLD["Global Dynamic Linker (nix-ld)"]:::core
        GEN["Atomic Symlink Pointer Management"]:::core
    end

    subgraph L3["Layer 3: Developer Engine"]
        DEV["Isolated Dev Shells (neuronix dev)"]:::dev
        CON["RAM Containers & OCI Runner"]:::dev
        GHO["Ephemeral Ghost RAM Persona"]:::dev
        BRN["CoW Workspace Branching"]:::dev
    end

    subgraph L4["Layer 4: Reliability & Provable Engine"]
        PSE[("Provable State Engine (Merkle StateRoot)")]:::provable
        HYP["Project Hyperion (Adaptive Execution Plane)"]:::provable
        DAE["Micro-Rust Systems Daemon (ast.sock)"]:::provable
        MCP["Model Context Protocol Server (JSON-RPC 2.0)"]:::provable
        TST["Continuous Industrial Assurance Taxonomy"]:::provable
    end

    L1 --> L2
    L3 --> L2
    L4 --> L2
    L4 --> L3

    classDef ux fill:#1e1e38,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef core fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef dev fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef provable fill:#3b1e54,stroke:#c084fc,stroke-width:2px,color:#f8fafc;
Loading

Storage Architecture & Maintenance

NEURONIX formats system drives with Btrfs using transparent Zstandard compression, structured subvolumes, and automated maintenance timers.

Btrfs Subvolume Topology

Storage partitioning uses an isolated subvolume layout:

Subvolume Mount Point Mount Options Purpose
@ / compress=zstd:3,noatime,space_cache=v2 Root filesystem and declarative system configuration pointers.
@nix /nix compress=zstd:3,noatime Immutable /nix/store directory.
@home /home compress=zstd:3,noatime User home directories and documents.
@snapshots /.snapshots compress=zstd:3,noatime Storage for manual and automated filesystem snapshots.
@swap /swap nodatacow,noatime Dedicated swapfile subvolume with Copy-on-Write disabled to prevent fragmentation. 
flowchart LR
    DISK[("Physical Storage Device<br>NVMe / SATA SSD")]:::disk --> ESP["ESP Partition (/boot)<br>UEFI System Bootloader"]:::boot
    DISK --> BTRFS[("Btrfs Root Storage Pool<br>Transparent Zstandard Compression")]:::pool
    
    BTRFS --> SUB_ROOT["@ (Root Filesystem)<br>Mount: /<br>Declarative System Pointers"]:::rootSub
    BTRFS --> SUB_HOME["@home (User Space)<br>Mount: /home<br>Preserved Across Rollbacks"]:::homeSub
    BTRFS --> SUB_NIX["@nix (Nix Store)<br>Mount: /nix<br>Cryptographic Immutability"]:::nixSub
    BTRFS --> SUB_SNAP["@snapshots (CoW Registry)<br>Mount: /.snapshots<br>Zero-Latency Snapshots"]:::snapSub
    BTRFS --> SUB_SWAP["@swap (Memory Swap Pool)<br>Mount: /swap (nodatacow)<br>ZRAM & Swapfile"]:::swapSub

    classDef disk fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef boot fill:#1e293b,stroke:#94a3b8,stroke-width:1.5px,color:#f8fafc;
    classDef pool fill:#1e1e38,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef rootSub fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef homeSub fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef nixSub fill:#312e81,stroke:#a78bfa,stroke-width:2px,color:#f8fafc;
    classDef snapSub fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#f8fafc;
    classDef swapSub fill:#334155,stroke:#cbd5e1,stroke-width:1.5px,color:#f8fafc;
Loading

Transparent Block Compression (ZSTD:3)

All read-write filesystem subvolumes use Zstandard level 3 (zstd:3) compression.

  • Disk Usage: Materially reduces physical storage consumption for compressible store paths and text/data files, with actual compression ratios varying by package composition.
  • Throughput: Minimizes raw byte transfers from NVMe/SATA storage, reducing solid-state write wear and improving real-world read times.

Auto TRIM and Omni Purging Storage Diet Engine

SSD performance degradation and sparse disk image inflation (in QEMU/KVM virtual machines) are addressed automatically through a multi-layered maintenance strategy:

  1. Host Auto TRIM (fstrim.timer): Issues discard calls (fstrim -av) across all mounted Btrfs and ESP partitions daily. This informs SSD controllers and hypervisors of deallocated blocks.
  2. Autonomous Garbage Collection (nix.gc): Runs weekly garbage collection (nix-gc.timer) with a 14-day retention policy (--delete-older-than 14d), establishing a practical policy trade-off between disk reclamation and long-term rollback availability while purging orphaned package closures.
  3. Hardlink Deduplication (nix.optimise & auto-optimise-store = true): Automatically hardlinks identical binary files across derivations within /nix/store; this can materially reduce duplicated store content, with exact savings depending on installed package composition.
  4. Dynamic Storage Guard (min-free & max-free): In-kernel Nix daemon safeguards disk space by triggering emergency collections if free space drops below 1.0 GiB until 3.0 GiB headroom is recovered.
  5. Systemd Journal Retention Ceiling (services.journald): Caps /var/log/journal storage at 500 MiB with 1-month retention, preventing runaway log file consumption.
  6. Ephemeral /tmp & Flatpak Runtime Hygiene: Purges stale /tmp files on every boot (boot.tmp.cleanOnBoot = true) and automatically prunes unreferenced Flatpak runtimes via flatpak-prune-unused.timer.
  7. One-Command Unified Diet (neuronix diet): Orchestrates Nix Store GC, Inode Deduplication, Flatpak Unused Pruning, Journal Vacuuming, and Host Physical TRIM in a single command, reporting reclaimed disk space.

Btrfs Metadata Balance Timer

Over time, Btrfs can accumulate sparsely populated block groups, causing ENOSPC errors even with remaining free space.

  • A systemd timer (btrfs-balance.timer) runs once a month (OnCalendar=monthly, Persistent=true).
  • It filters and compacts under-allocated chunks (btrfs balance start -dusage=10 -musage=10 /), maintaining filesystem performance without manual intervention.

Filesystem Options: Btrfs vs EXT4

While Btrfs is the default and recommended filesystem for NEURONIX, standard EXT4 is fully supported out of the box:

  • Kernel & Driver Support: The Linux kernel includes native drivers for both filesystems via boot.supportedFilesystems = [ "btrfs" "ntfs" "exfat" "ext4" "vfat" ].
  • Automated Configuration: When selecting EXT4 in Calamares Manual Partitioning, nixos-generate-config automatically captures the partition UUID and writes fileSystems."/".fsType = "ext4" to hardware-configuration.nix.
  • Generation Rollback Independence: System generation immutability and atomic rollback mechanisms reside in the Nix store engine, not the underlying filesystem. Generation rollbacks in systemd-boot operate identically on both Btrfs and EXT4.
Architectural Dimension Btrfs (Default) EXT4 (Supported Alternative)
Partition Structure Structured subvolumes (@, @nix, @home, @snapshots, @swap) Traditional monolithic root partition (/)
Transparent Compression In-kernel Zstandard level 3 (zstd:3) materially reduces storage usage for compressible data Uncompressed storage (requires larger disk allocation)
Maintenance Workload Automated monthly chunk rebalancing via btrfs-balance.timer Zero filesystem maintenance overhead (standard fsck)
I/O Overhead Copy-on-Write metadata tracking Minimal filesystem overhead, stable raw write throughput
Recommended Use Case Modern NVMe/SATA SSDs with limited physical storage capacity Traditional magnetic disks (HDDs), USB storage, or high-throughput databases

Memory Pressure Management

To prevent system lockups under memory exhaustion, NEURONIX implements an intelligent four-tier memory management strategy using ZRAM, zswap deactivation, tuned kernel paging parameters, zero-wear storage fallback, and active PSI monitoring:

Tier Component Configuration / Path Action
1. In-RAM Swap Pool ZRAM (ZSTD) zramSwap.priority = 32767, memoryPercent = 100 Compressed RAM block device dynamically sized to 100% of host RAM. Highest kernel priority routes all paging to RAM first.
2. Double-Compression Defense zswap.enabled = 0 boot.kernelParams Disables in-kernel zswap to eliminate duplicate compression and unnecessary CPU overhead.
3. Zero-Wear Storage Fallback Physical Swap / @swap Low priority (-2), nodatacow subvolume Preserves secondary swap and hibernation (resume=UUID=...) while keeping physical SSD writes at 0 bytes under normal loads.
4. Eviction & PSI Guard systemd-oomd / earlyoom /proc/pressure/memory Monitors Pressure Stall Information (PSI) to terminate runaway processes before desktop freezes.

ZRAM In-Memory Swap Pool & Prioritization

  • Configured with priority = 32767 and the ZSTD compression algorithm.
  • Provides an in-memory swap pool expanding effective memory headroom by 1.5x to 2.7x on compressible data, maintaining interactive responsiveness under memory pressure with minimal CPU overhead.
  • Because ZRAM is assigned the maximum Linux swapon priority (32767), secondary disk partitions remain untouched at 0 bytes used, providing zero-wear protection for modern NVMe SSDs (including QLC and TLC media).

Kernel Paging Tuning & Zswap Elimination

  • zswap.enabled = 0: Explicitly disables kernel zswap to avoid compressing memory twice (once in zswap, once in ZRAM).
  • vm.swappiness = 180 and vm.page-cluster = 0: Shifts idle background memory into ZRAM early with zero readahead latency, keeping physical uncompressed memory free for compilers and desktop applications.
  • vm.vfs_cache_pressure = 50: Retains directory and inode caches to prevent filesystem stuttering.

Pressure Stall Information (PSI) & OOM Protection

  • The kernel continuously monitors memory pressure via Pressure Stall Information (/proc/pressure/memory).
  • When memory stall duration exceeds configured safety thresholds, the userspace OOM daemon terminates the responsible application, preventing desktop UI freezes while preserving system stability.

Hardware Compatibility Matrix & Profiles

NEURONIX includes declarative configurations addressing standard desktop and laptop hardware requirements across 27 subsystem domains. For empirical platform qualifications across reference platforms (ThinkPad, Framework, Dell XPS, ASUS ROG Zephyrus, QEMU KVM, Apple Silicon), see the Reference Hardware Qualification Matrix and machine-readable evidence in data/hardware_qualification.json.

Reference Platform Qualification Matrix

Reference Platform Processor / Architecture GPU Subsystem Wi-Fi / Bluetooth Audio Duplex Suspend / S3 Qualification Tier
Generic QEMU / KVM Micro-VM Virtual x86_64 (KVM Host) VirtIO-GPU / DRM VirtIO-Net PipeWire Dummy S3 / S4 Supported Tier 1 (CI Validated)
Lenovo ThinkPad T14 / P14s (Gen 4/5) AMD Ryzen 7 PRO (Zen 4) AMD Radeon 780M (Mesa RDNA3) Qualcomm Atheros / MT7922 Realtek ALC257 (PipeWire) Deep (mem_sleep=deep) Tier 1 (Target Reference)
Framework Laptop 13 (Intel Core Ultra) Intel Core Ultra 7 155H Intel Arc Graphics (Xe-LPG) Intel Wi-Fi 6E AX211 Realtek ALC295 (PipeWire) Modern Standby (s2idle) Tier 1 (Target Reference)
Custom AMD Workstation (Ryzen + RDNA3) AMD Ryzen 9 7950X (Zen 4) AMD Radeon RX 7900 XTX (Mesa RADV) Intel I225-V 2.5GbE / AX210 Realtek ALC4080 (PipeWire) S3 Sleep Supported Tier 1 (Desktop Reference)
Intel Desktop Workstation (Core + Arc) Intel Core i7-14700K (Raptor Lake) Intel Arc A770 / UHD Graphics 770 Realtek RTL8125 2.5GbE / AX211 Realtek ALC1220 (PipeWire) S3 Sleep Supported Tier 1 (Desktop Reference)
Dell XPS 15 / 16 (Hybrid Dual-GPU) Intel Core i7/i9 (Alder/Raptor Lake) Intel Iris Xe + NVIDIA RTX 4060 Killer Wi-Fi 6E AX1675 Realtek ALC3281 (PipeWire) Modern Standby (s2idle) Tier 2 (PRIME Offload Validated)
ASUS ROG Zephyrus G14 (AMD + NVIDIA) AMD Ryzen 9 + NVIDIA RTX 4060 AMD Radeon 780M + RTX 4060 Mobile MediaTek MT7922 Wi-Fi 6E Realtek HD Audio (PipeWire) Deep (mem_sleep=deep) Tier 2 (Hybrid PRIME Qualified)
Apple Silicon (aarch64 via UTM / Asahi) Apple M1/M2/M3 (aarch64) Apple AGX / VirtIO-GPU Broadcom Wi-Fi / VirtIO PipeWire Core Suspend Supported Tier 2 (Experimental aarch64)

Hardware & Subsystem Configuration Matrix (27 Pillars)

Subsystem Domain Technical Objective Declarative Implementation Configuration Module
Package Licensing Proprietary drivers and runtime compatibility (Steam, NVIDIA, codecs) nixpkgs.config.allowUnfree = true modules/core/default.nix
RTC Synchronization Real-time clock synchronization in Windows dual-boot environments time.hardwareClockInLocalTime (conditional for Windows dual-boot) modules/hardware/boot.nix
Filesystem Maintenance Metadata chunk fragmentation prevention on active Btrfs volumes Automated monthly btrfs-balance systemd timer modules/services/storage.nix
Storage Reclamation Autonomous SSD TRIM and sparse disk reclamation (Auto-TRIM) Daily fstrim.timer + auto-optimise-store hardlink dedupe modules/services/storage.nix
Application Ecosystem Sandboxed desktop application integration without root modification Dual-layer distribution: immutable Nix core + Flathub Flatpak modules/services/flatpak.nix
Boot Partition Guard EFI System Partition storage overflow prevention 1.0 GiB ESP standard with generation prune threshold (configurationLimit = 15) modules/hardware/boot.nix
Offline Firmware out of the box Wi-Fi and Bluetooth chipset connectivity Full redistributable firmware bundle (Broadcom, Realtek, Intel) modules/hardware/firmware.nix
Hybrid Graphics Dynamic dGPU power gating on Optimus/PRIME laptops Declarative NVIDIA PRIME Render Offload configuration (Status: Implemented) modules/hardware/nvidia-prime.nix
Secure Boot Compatibility with UEFI Secure Boot firmware policies Lanzaboote signed boot integration (Status: Experimental, requires MOK enrollment) modules/hardware/secureboot.nix
Portal Integration Native file-chooser dialog synchronization under Wayland Explicit portal backend mapping via portals.conf modules/services/flatpak.nix
Power Management Modern Standby battery drain reduction on mobile hardware Kernel directive mem_sleep_default=deep + power-profiles-daemon modules/hardware/power.nix
Dual Boot Detection UEFI boot partition discovery for multi-boot operating systems Native systemd-boot EFI discovery without legacy os-prober modules/hardware/boot.nix
Memory Mapping Limit Thread allocation and memory map exhaustion prevention High-concurrency tuning: vm.max_map_count = 2147483642 modules/hardware/boot.nix
HiDPI Display Scaling Subpixel and fractional scaling blur elimination under Wayland Wayland Ozone flags enabled for Chromium and Electron runtimes modules/services/desktop-tweaks.nix
Boot Watchdog Power-loss protection during bootloader update transactions Hardware UEFI watchdog timeouts (30s runtime, 10min reboot) modules/hardware/boot.nix
Input Methods Multilingual text input support (CJK and complex scripts) Pre-configured Fcitx5 IME framework modules/services/desktop-tweaks.nix
Trust Store Injection Corporate and development Root CA certificate enrollment Dedicated certificate injection script (neuronix-add-ca) modules/services/network.nix
Memory Pressure Guard System responsiveness and freeze prevention under memory saturation ZRAM compressed RAM swap (ZSTD, 100% RAM) + systemd-oomd PSI modules/services/memory-shield.nix
Audio Processing Low-latency audio processing and high-fidelity Bluetooth communication PipeWire session manager with LDAC, AptX HD, and LC3Plus codecs modules/hardware/audio.nix
Battery Conservation Battery cycle life extension during prolonged AC operation Kernel sysfs charge ceiling daemon (charge_control_limit_max = 80) modules/hardware/power.nix
Video Decoding Hardware-accelerated video decode offloading (H.264, HEVC, AV1) Pre-configured VA-API and NVDEC acceleration libraries modules/hardware/nvidia-prime.nix
Network Portals Captive portal detection on public and enterprise Wi-Fi Automated NetworkManager connectivity polling modules/services/network.nix
Printing Subsystem Driverless network and USB printing IPP Everywhere, Apple AirPrint, and Mopria service integration modules/services/printing.nix
External Media High-performance removable storage throughput In-kernel ntfs3 and native exfat automounting modules/services/storage.nix
Analog Audio Power DAC click and pop elimination on 3.5mm analog outputs Inactive DAC power-save state disabled (snd_hda_intel power_save=0) modules/hardware/audio.nix
Swap Integrity Filesystem corruption prevention on Btrfs swapfiles Dedicated @swap subvolume with Copy-on-Write disabled (nodatacow) installer/calamares/modules/partition.conf
Microcode Updates Processor security vulnerability mitigations (Spectre, Zenbleed) Automated processor microcode updates enabled for Intel and AMD modules/hardware/cpu.nix
Identity & Signing Secure cryptographic key agent forwarding on Wayland sessions GnuPG Agent with Pinentry graphical prompt and SSH_AUTH_SOCK modules/services/security.nix

Command Line Reference (neuronix)

The integrated neuronix CLI utility manages system telemetry, storage optimization, developer shells, and generation rollbacks:

USAGE:
  neuronix <COMMAND> [OPTIONS]

Commands

Command Arguments Description Example
status None Shows system version, storage usage, active systemd timers, and hardware matrix status. neuronix status
shield [--json] Displays live memory pressure diagnostics, layered swap hierarchy, zswap status, and PSI metrics. neuronix shield --json
generations None (or list) Lists system generations with timestamps and indicates the active generation. neuronix generations
battery [80 | 100 | status] Reads or modifies the laptop battery charging threshold limit. neuronix battery 80
diet None Runs garbage collection, deduplicates /nix/store hardlinks, and issues filesystem TRIM. neuronix diet
dev <stack> Starts an isolated development shell (python, rust, node, ai, go, web3). neuronix dev rust
run [flags] <command... | packages...> Adaptive Workload Execution Engine (Tiers 0-3) and ephemeral nix-shell. neuronix run --intent "build" cargo build
sandbox [target|iso] [options] In-memory OS Micro-VM sandbox with ISO booting, Btrfs CoW, and 3D acceleration. neuronix sandbox --smoke-test
try [target|iso] [options] (Alias) Backward-compatible alias for neuronix sandbox. neuronix try --smoke-test
verify <package> Tests whether a derivation evaluates cleanly against the nixpkgs closure via dry-build. neuronix verify ripgrep
center None Opens the graphical NEURONIX Control Center (or runs --cli in headless environments). neuronix center
mcp None Starts the Model Context Protocol (MCP) server over stdio adhering to JSON-RPC 2.0. neuronix mcp
check-update None Checks upstream flake repository and remote releases for system updates. neuronix check-update
upgrade [--staged | --switch] Performs atomic system upgrade (staged by default for reboot, or instant switch). neuronix upgrade --staged
doctor [--json | --output <f> | --proof] Deep diagnostic probe producing privacy-sanitized reports and authoritative SystemVerificationReceipts. neuronix doctor --proof
welcome [--cli | --disable-autostart] Interactive first-boot welcome wizard and distro onboarding guide. neuronix welcome
quickstart [list | install <id>] Curated Flathub desktop & engineering app hub (zero store pollution). neuronix quickstart list
kernel [status | list | set <flv>] Declarative kernel flavor manager (default, zen, lts, latest, hardened). neuronix kernel list
manual [topic | --list] Reads offline system manual and architecture reference (/etc/neuronix/manual/). neuronix manual config
sentinel [status | confirm] Autonomous Wayland/desktop boot watchdog with auto-rollback on crash-loops. neuronix sentinel status
diff [genA] [genB] Generational forensic diff engine analyzing package closures, kernel changes, and store paths. neuronix diff 41 42
distill <packages...> [--dry-run] Imperative-to-declarative reverse engine compiling packages into Flake configuration. neuronix distill ripgrep htop
container <target> [options] Ephemeral RAM development container with Dynamic FHS, OCI runner, and stack runner. neuronix container oci://alpine:latest
tune [profile | --status] Declarative workload-tailored performance matrix (gaming, battery, audio-daw, balanced). neuronix tune gaming
mesh [status | peers] Local P2P zero-config binary cache mesh over mDNS/Avahi without centralized Hydra/Cachix. neuronix mesh peers
daemon [status | ping | ast] Surgical micro-Rust daemon and unified live system AST state query engine. neuronix daemon ast
ghost [--run <cmd>] Disposable zero-trace ephemeral session in volatile RAM overlay with instant vaporization. neuronix ghost --run "bash"
branch [create | list | revert] Instantaneous Btrfs CoW / Reflink project workspace branching for risk-free experimentation. neuronix branch create . experiment
ebpf [status | policy <pkg>] Declarative eBPF LSM capability status and security policy contract generator. neuronix ebpf status
state [show | verify | explain | diff | history | recover | prove] Provable State Engine: 5-leaf Merkle StateRoot calculation, cryptographic lineage, and verified recovery. neuronix state verify
hyperion [status | negotiate | proof | verify | list] Provable Adaptive Execution Architecture: HDS synthesis, domain lifecycle, and Merkle Domain Proofs. neuronix hyperion status
verify-passport [passport.json] [--public-key <k>] [--graph] [--trace <target>] Zero-dependency standalone offline verification engine for system release passports and lineage graphs. neuronix verify-passport dist/verification-passport.json --graph --trace release
graph [--json] [--format ascii|dot] [--trace <target>] Authoritative 18-node Directed Evidence Graph visualization and lineage tracing from source to release. neuronix graph --trace release
verify-release [proof.json] [--iso <path>] Cryptographic verification of proof-carrying release bundle against StateRoot and Evidence Graph. neuronix verify-release dist/neuronix-os-v1.0.5.proof.json
version None (-v, --version) Displays package version, architecture, and license information. neuronix version
help None (-h, --help) Displays available commands and syntax summaries. neuronix help

Core System Components

1. Declarative Calamares Installation Engine

The graphical installer functions as a declarative flake generator (ADR-002):

  • Modular Pipeline: Complete declarative sequence configuration (welcome, locale, keyboard, partition, users, summary, mount, shellprocess@neuronix-engine, and finished) ensures end-to-end setup stability.
  • Robust User Account Provisioning: Calamares users.conf standardizes default user attributes, wheel administration group bindings, and user shell definitions without runtime crash risks.
  • Automated Mount Orchestration: Dedicated mount.conf declares swap and EFI system partition mount targets into /mnt before dispatching the installation engine.
  • Hardened Live ISO Environment: Live media boots into GNOME Wayland with automated GDM user auto-login (nixos account with initialized home, shell, and passwordless sudo privileges), preventing session startup crashes.
  • Declarative Flake Synthesis: Writes corresponding /mnt/etc/nixos/flake.nix and configuration.nix files tailored to the target system.
  • Resilient Storage Architecture: Formats target storage using the Btrfs subvolume layout (@, @nix, @home, @snapshots, @swap).
  • Hermetic System Deployment: Runs nixos-install --flake /mnt/etc/nixos#neuronix-desktop, producing a fully declarative system installation upon first boot with autonomous network detection and offline fallback support.

2. System Control Center (Conductor)

The official graphical desktop control surface and administration hub engineered under the "Quiet Systems UI" doctrine :

Conductor Operational Surfaces & Visual States

1. Overview Surface

Conductor - Overview Surface

  • Function: Real time operating system substrate summary (Neuronix OS, kernel release, active generation state, root filesystem utilization) and live hardware telemetry (CPU model, physical memory, display adapter, battery charge ceiling) with direct one-click action triggers (Staged Upgrade, Rollback, Diagnostics, Terminal).
2. System Generation Timeline

Conductor - System Generation Timeline

  • Function: Inspects declarative NixOS generation records via an interactive Treeview with dual horizontal and vertical scrollbars. Houses declarative maintenance operations including atomic rollback, staged upgrade preparation, and storage hygiene (Storage Diet garbage collection and TRIM).
3. Modular Developer Stacks & Diagnostics

Conductor - Developer Stacks & Diagnostics

  • Function: Provides instant, isolated access to hermetic development environments (AI System, Python Substrate (uv), Rust Substrate (cargo), Node.js Substrate (pnpm), AI Substrate (PyTorch)) and diagnostic utilities (Terminal Shell, System Doctor, Curated Apps, Launch Welcome Tour).
4. Cryptographic Provenance & Storage Contracts

Conductor - Advanced Cryptographic Provenance

  • Function: High assurance cryptographic audit surface displaying the Merkle StateRoot commitment, offline verification passport status (1,384/1,384 verified), directed evidence lineage graph, Btrfs subvolume layouts (@, @nix, @home, @snapshots, @swap), kernel memory policies, and one click diagnostic clipboard export.
5. Active Mutation State (Working)

Conductor - Active Mutation State

  • Function: Displays calm blue status feedback (● Staging System Upgrade...) while background operations execute asynchronously. Enforces strict mutex locking (is_busy) across all action buttons to eliminate race conditions and prevent concurrent state transitions.
6. Advisory & Maintenance State (Attention)

Conductor - Attention & Advisory State

  • Function: Non-intrusive amber indicator (● Attention: Updates Pending) signaling available upstream channels or advisory maintenance recommendations without jarring notification popups.

Key Architectural Invariants & Features

  • Progressive Disclosure Architecture (4 Clean Tab Surfaces): Logical workflow separation across Overview, System, Developer, and Advanced surfaces without visual clutter.
  • Responsive & Accessible Geometry: Dynamic resizable window (minsize(640, 440), default 720x520, centered on screen) with fluid grid/pack weight expansion, explicit spacing tokens (4, 8, 12, 16, 24, 32), and semantic typography scale following desktop accessibility settings.
  • Theme Awareness & Translucent Dark Mode: Automatic detection of desktop dark/light appearance (GTK, KDE Plasma, GNOME GSettings) with deep Tokyo Night and Arc-Darker palettes (#13141c, #16161e, #1a1b26, #24283b) and subtle window alpha translucency (-alpha 0.90) for an authentic Ghostty terminal aesthetic.
  • Pure-Text Button Design: Clean, modern, typography-first button design free from icon clutter, matching high-end enterprise terminal tools.
  • Non-Blocking Telemetry Worker: Asynchronous background worker thread (threading.Thread with thread-safe UI event queue) preventing interface freeze during hardware inspection, complemented by gentle 45s auto-refresh and instant on-demand refresh (F5 or Ctrl+R).
  • Non-Silent Diagnostic Feedback: Descriptive user facing dialogs for missing desktop terminal emulators rather than silent process dismissal.
  • Keyboard-First Navigation: Full tab order navigation with standard accelerators: F5 / Ctrl+R (Refresh), Ctrl+T (Terminal), Ctrl+U (Upgrade), Ctrl+Z (Rollback), Ctrl+D (Doctor), Ctrl+1..4 (Switch Tabs), and Ctrl+Q / Esc (Exit).
  • Interface Modes: Runs seamlessly via native desktop graphical launcher or full headless CLI mode (neuronix-center --cli, --list-generations, --version).

3. Isolated Development Environments (neuronix dev)

Pre-configured development shells running in RAM via nix-shell:

# Python toolchain (Python 3.12, uv, ruff, pyright, postgresql client)
neuronix dev python

# Rust toolchain (rustc, cargo, rust-analyzer, clippy, mold)
neuronix dev rust

# Node.js toolchain (Node.js 20 LTS, pnpm, typescript, eslint)
neuronix dev node

# AI/ML toolchain (PyTorch, CUDA runtimes, Ollama, JupyterLab, pandas)
neuronix dev ai

# Go toolchain (Go compiler, gopls, golangci-lint, delve)
neuronix dev go

# Web3 toolchain (Rust, Cargo, Node.js, solana-cli)
neuronix dev web3

4. In Memory Micro VM Simulation (neuronix sandbox)

Enables verification of proposed system configurations, kernel options, or untrusted software inside an ephemeral QEMU micro-VM running entirely in memory (/dev/shm) with read-only 9P store pass-through, Autonomous OS Fabric, Windows 11 Autopilot, and Btrfs CoW snapshot trees:

# Execute automated smoke test inside the in-memory Micro-VM
neuronix sandbox --smoke-test

# Evaluate a target configuration file inside an isolated sandbox
neuronix sandbox ./configuration.nix --timeout 60

# Provision and launch verified guest operating systems automatically
neuronix sandbox get alpine
neuronix sandbox get ubuntu-24.04
neuronix sandbox get arch
neuronix sandbox get debian-12
neuronix sandbox get windows-11

# Instantaneous sub-millisecond Btrfs CoW snapshots and branching
neuronix sandbox snapshot create test-checkpoint
neuronix sandbox snapshot list
neuronix sandbox snapshot restore test-checkpoint
neuronix sandbox branch base-dev feature-experiment

5. Model Context Protocol (MCP) Server

NEURONIX includes a built in Model Context Protocol server communicating over stdio adhering to JSON-RPC 2.0 (Protocol Version 2024-11-05). It provides structured tools, resources, and prompt templates for autonomous development agents:

  • Tools: Exposes neuronix_status, neuronix_diet, neuronix_verify, neuronix_undo, neuronix_shadow_eval, neuronix_doctor, neuronix_check_update, neuronix_upgrade, neuronix_manual, neuronix_sentinel, neuronix_diff, neuronix_distill, neuronix_container, neuronix_sandbox, neuronix_tune, neuronix_mesh, neuronix_ast_query, neuronix_workspace_branch, and neuronix_ghost_exec.
  • Architectural Convergence: All state-mutating tools (neuronix_diet, neuronix_undo, neuronix_upgrade) converge strictly through the unified, transactional Python core (neuronix_core.operations). They enforce POSIX mutual exclusion via OperationLock, exact generation predecessor verification, and transaction journaling (TransactionJournal), maintaining 100% parity with CLI and GUI control center workflows.
  • Clean Update Separation: Update checks isolate local system commits from pinned upstream Nixpkgs hashes, eliminating cross-domain SHA comparisons.
  • Resources (resources/list, resources/read): Exposes all 11 system manual chapters under the neuronix://manual/* URI scheme for instant semantic ingestion.
  • Prompts (prompts/list, prompts/get): Exposes neuronix_system_directive containing declarative operational guardrails for AI models.
# Launch JSON-RPC 2.0 stdio MCP server
neuronix mcp

6. OpenCode AI Coding Agent & Autonomous Updates

A built-in, declarative AI coding agent providing interactive TUI and CLI-driven intelligence across all desktop environments (KDE Plasma, GNOME, Hyprland). Powered by upstream OpenCode (anomalyco/opencode). See the OpenCode Architecture Specification for comprehensive design details.

  • Pre-installed by Default: Enabled out of the box (neuronix.services.opencode.enable = true;), exposing application launcher entries (opencode.desktop) and desktop shortcuts across all desktop environments.
  • Native MCP Substrate Integration: Pre-configured with the local NEURONIX Model Context Protocol (MCP) server, granting OpenCode immediate access to system inspection, verification, and atomic rollback tools.
  • Autonomous System Manual Grounding: OpenCode automatically discovers root directives at /etc/neuronix/SYSTEM_PROMPT.md, /etc/neuronix/AGENTS.md, and $NEURONIX_AI_DIRECTIVE without requiring manual CLI invocations (neuronix manual).
  • Autonomous Background Updates: Powered by neuronix-opencode-update.timer which checks and synchronizes upstream releases daily without touching physical store immutability or risking running system stability.
  • Zero-Residue Removal: Easily disabled via neuronix.services.opencode.enable = false; or via the NEURONIX Center interface. Disabling immediately removes all binaries, background timers, and desktop shortcuts.
# Launch interactive terminal user interface (TUI)
opencode

# Start OpenCode directly in a specific project directory
opencode /path/to/project

# Execute prompts directly via non-interactive CLI mode
opencode run "explain flake inputs in flake.nix"

# Manage Model Context Protocol (MCP) connections
opencode mcp list

# Check OpenCode version and upgrade options
opencode --version
opencode upgrade --help

7. Autonomous Update Architecture & Desktop Notifier

A gated, generation preserving update architecture providing continuous rolling freshness without un-gated instability or active session disruption. See the Update & Storage Specification for architectural details.

  • Lightweight Desktop Notifier: A background systemd timer (neuronix-update-check.timer) queries upstream flake metadata (< 50 KB) and broadcasts desktop notifications (notify-send) across KDE Plasma, GNOME, and Hyprland when a new generation is available.
  • 1-Click Staged Upgrades: By default, upgrades are built in the background using nixos-rebuild boot (neuronix upgrade --staged), registering the new generation to the bootloader without restarting the display server or interrupting running applications.
  • User Sovereignty & Full Automation: Unattended auto-upgrades can be toggled via neuronix.services.updates.autoUpgrade = true; or via the NEURONIX Center GUI.
# Query upstream repository and flake release status
neuronix check-update

# Stage system upgrade in background (activates cleanly on next boot)
neuronix upgrade --staged

# Perform immediate live switch to new system generation
neuronix upgrade --switch

8. First Boot Welcome Hub & Onboarding Wizard

A unified first-boot welcoming experience providing new users with immediate system orientation, quick links, system status telemetry, and shortcuts to critical distro tasks. See the Onboarding & Distro Polish Specification.

  • Hybrid GUI & CLI Operation: Launches automatically as neuronix-welcome.desktop upon initial desktop login, or interactively in terminal sessions via neuronix welcome --cli.
  • Autostart Governance: Seamlessly toggle auto-launch via neuronix welcome --disable-autostart or --enable-autostart.
# Launch interactive terminal onboarding guide
neuronix welcome --cli

# Disable autostart on future desktop logins
neuronix welcome --disable-autostart

9. System Doctor & Privacy Sanitized Issue Reporter

An automated deep system diagnostics engine that inspects hardware, kernel dmesg rings, active generation, filesystem health, and systemd maintenance timers.

  • Privacy First Data Scrubbing: Automatically scrubs and masks real local usernames (<sanitized-user>), hostnames (<sanitized-host>), IPv4/IPv6 addresses ([REDACTED-IP]), and hardware MAC identifiers ([REDACTED-MAC]). Personal identifiers are redacted, while system architecture and hardware topology remain intentionally visible for diagnostic accuracy.
  • GitHub Issue Ready: Produces formatted Markdown at /tmp/neuronix-doctor.md ready to copy-paste directly into community bug reports.
# Run diagnostics and produce /tmp/neuronix-doctor.md
neuronix doctor

# Output structured JSON for MCP agents and automated tools
neuronix doctor --json

10. Curated Quickstart App Hub (Flatpak)

A curated 1-click catalog of daily desktop applications (Browsers, Development IDEs, Communication, Multimedia, Productivity) powered entirely by Flathub container sandboxing.

  • Immutable Store Protection: Preserves /nix/store immutability by avoiding arbitrary native package pollution for transient desktop software.
# List curated application catalog
neuronix quickstart list

# Install Brave Browser via Flathub sandbox
neuronix quickstart install brave

# Install VS Code via Flathub sandbox
neuronix quickstart install vscode

11. Declarative Kernel Flavor Manager

An intuitive declarative interface to select and switch upstream Linux kernel packages (default, zen, lts, latest, hardened) with staged rollback protection.

  • Declarative NixOS Option: Declared in modules/hardware/boot.nix via neuronix.hardware.kernelFlavor.
  • Staged Compilation: Builds the new kernel generation safely via Staged Upgrade, ensuring fallback to the previous working kernel if new hardware regressions occur.
# Inspect currently running kernel and configured flavor
neuronix kernel status

# Compare available kernel flavors and target workloads
neuronix kernel list

# Set active kernel flavor to Zen (low-latency desktop & gaming)
neuronix kernel set zen

12. System Embedded Manual & Autonomous AI Grounding

NEURONIX embeds an immutable, 11-chapter technical manual directly into the operating system filesystem at /etc/neuronix/manual/ via pure Nix derivations (modules/core/manual.nix):

  • Always Synchronized: Directly symlinked to /nix/store, automatically re-evaluated and updated during every system generation rebuild (nixos-rebuild switch or neuronix upgrade).
  • Autonomous AI Preloading: AI agents (OpenCode, Cursor, Claude, Antigravity) automatically discover root directives at /etc/neuronix/SYSTEM_PROMPT.md, /etc/neuronix/AGENTS.md, and $NEURONIX_AI_DIRECTIVE without requiring manual user commands.
  • Unified Multi-Interface Access: Seamlessly accessible via CLI (neuronix manual [topic]), OpenCode MCP integration, and native MCP protocol (tools/call, resources/read, prompts/get).
# Display full manual index and chapter topic list
neuronix manual index

# Query specific architectural, configuration, or operational manual chapters
neuronix manual config
neuronix manual storage
neuronix manual ai

13. Enterprise Security Boundary & Hardened Trust Architecture

NEURONIX implements rigorous least-privilege security boundaries and transactional invariants:

  • Nix Daemon Least-Privilege (SEC-TRUST-001): Restricted to nix.settings.trusted-users = [ "root" ];. Ordinary wheel users build in isolated sandboxes and cannot substitute arbitrary binary store paths.
  • Privileged Operation Allow-List: Mutation operations (rollback, gc, trim, battery, ca-install) are strictly vetted through neuronix_core.operations with input sanitization and command injection defense.
  • Content-Addressed CA Enrollment: Enterprise root certificates are validated for PEM delimiters and stored with cryptographic SHA-256 content-addressing (neuronix-ca-<sha256>.crt) to prevent path traversal.
  • Fail-Closed Release Signing: Checksum signing strictly enforces genuine Ed25519 private keys, eliminating insecure mock key fallbacks.
  • Transactional State & Recovery: All updates and generation switches use non-blocking OperationLock mutual exclusion, TransactionJournal crash recovery, and automated rollback upon health check regressions.
  • Pure Declarative Subsystem Options:
    • neuronix.hardware.kernelFlavor: upstream kernel selection ("default", "latest", "lts", "zen", "hardened").
    • neuronix.power.sleepMode: modern suspend states ("auto", "deep", "s2idle").
    • neuronix.boot.windowsDualBoot: clean RTC clock synchronization without ad-hoc scripts.
    • neuronix.audio.antiPop: opt-in DAC power-management anti-pop override while preserving laptop power savings.
    • neuronix.desktop.inputMethodProfile: modular internationalization ("standard", "cjk-full", "minimal").

14. Autonomous Boot-Sentinel & Crash-Loop Rollback

An autonomous boot reliability monitor that protects against unbootable Wayland compositor crashes, broken display managers, or faulty kernel configurations:

  • Active Assessment Watchdog Timer: Upon boot, neuronix-boot-sentinel.service arms neuronix-boot-sentinel-watchdog.timer with a configurable assessment timeout (default: 60s). If the graphical target or Wayland session fails or enters a crash loop before confirmation, the watchdog fires neuronix-boot-fallback.service.
  • Unified Transactional Rollback Engine: The fallback handler invokes the core Python neuronix_core.rollback.execute_rollback(target_generation=lkg) with full TransactionJournal crash-safety and postcondition validation rather than brittle raw symlink mutations.
  • Explicit Session Confirmation: Successful desktop login or running neuronix sentinel confirm disarms the active watchdog timer and commits the current generation into /var/lib/neuronix/sentinel/lkg-generation.
  • Full Parity: Accessible via CLI (neuronix sentinel), GUI Control Center, and JSON-RPC MCP server (neuronix_sentinel).
flowchart TD
    BOOT(["System Boot: Generation N"]):::entryNode --> WATCH["Arm Sentinel Watchdog<br>Systemd Assessment Window"]:::watchNode
    WATCH --> CHECK{"Desktop Session<br>Healthy?"}:::checkNode

    CHECK -->|"Session Initialized"| COMMIT(["Disarm Watchdog & Commit LKG<br>Generation N Certified"]):::successNode
    CHECK -->|"Crash / Panic / Timeout"| FAIL["Crash Loop Detected<br>Fire Fallback Service"]:::failNode

    FAIL --> ROLLBACK["Execute Transactional Rollback<br>Atomic Profile Switch"]:::rollbackNode
    ROLLBACK --> RESTORE(["Reboot into Last Known Good State<br>Predecessor Generation Active"]):::restoreNode

    classDef entryNode fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef watchNode fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#f8fafc;
    classDef checkNode fill:#1e1e38,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef successNode fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef failNode fill:#881337,stroke:#f43f5e,stroke-width:2px,color:#f8fafc;
    classDef rollbackNode fill:#4c0519,stroke:#fb7185,stroke-width:2px,color:#f8fafc;
    classDef restoreNode fill:#042f2e,stroke:#2dd4bf,stroke-width:2px,color:#f8fafc;
Loading 
# Query active boot health assessment, watchdog timer state, and LKG generation
neuronix sentinel status

# Manually confirm current generation and disarm active watchdog timer
neuronix sentinel confirm

15. Generational Forensic Diff Engine (neuronix diff)

A deep forensic analysis engine that compares system generations to pinpoint exact causes of breakage or configuration drift:

  • Authoritative Three Tier Analytical Forensics:
    • Tier 1 (System Metadata): Kernel version, NixOS release ID, creation timestamps, and active profile symlinks.
    • Tier 2 (Authoritative Store Closures): Leverages nix store diff-closures to analyze exact closure paths, added/removed packages, and upgraded versions with exact delta size byte accounting (KiB/MiB).
    • Tier 3 (Convenience Deltas): Forensics for executables (/sw/bin) and systemd background services (/etc/systemd/system).
  • Zero Ambiguity: Defaults to comparing the active generation against its immediate predecessor if arguments are omitted.
  • Machine-Readable Telemetry: Supports --json emitting structured Tier 1-3 telemetry for automated regression analysis by AI copilots and CI pipelines.
# Diff active generation against previous generation with 3-tier analysis
neuronix diff

# Compare two arbitrary generations (e.g. Generation 40 vs 42)
neuronix diff 40 42

# Emit machine-readable JSON diff report
neuronix diff --json

16. Imperative-to-Declarative Reverse Engine (neuronix distill)

Bridges the gap between ephemeral experimentation (neuronix run) and declarative NixOS immutability:

  • Reverse-Compilation Pipeline: Captures ad-hoc packages tried imperatively, verifies them against pure nixpkgs closures, and compiles them directly into declarative Nix code at modules/custom/user-packages.nix.
  • Managed Safety Boundary & Protection: Generates # AUTO-GENERATED BY NEURONIX DISTILL boundary headers. Refuses to overwrite human-crafted configurations unless explicitly overridden with --force.
  • AST Syntax Pre-Flight Validation: Validates the generated Nix expression with nix-instantiate --parse before modifying any files, ensuring the system flake cannot be broken by syntax errors.
  • Dry-Run Mode: Supports --dry-run to preview the generated Nix configuration without writing changes to disk.
# Preview declarative Nix configuration for packages
neuronix distill ripgrep fd htop --dry-run

# Persist packages into modules/custom/user-packages.nix
neuronix distill ripgrep fd htop

# Force overwrite of destination module even if human-modified
neuronix distill ripgrep fd htop --force

17. Ephemeral Zero Copy RAM Development Container (neuronix container)

Enables instantaneous, isolated code experimentation, OCI container execution, and untrusted repo exploration without touching workstation storage or risking system state:

  • Strict RAM-Backed Workspace (/dev/shm): Clones or unpacks target repositories into a temporary RAM filesystem with zero disk writes. Refuses silent physical disk fallback (require_ram=True) when RAM isolation is requested.
  • Dynamic Transparent FHS Emulation: Automatically resolves /lib64/ld-linux-x86-64.so.2 and glibc shared library paths so foreign pre-compiled binaries (Go, Rust, Node, Python C-extensions) run out of the box without container bloat.
  • Daemonless OCI Image Runner: Pulls and extracts Docker Hub and OCI container images (oci://, docker://) directly into RAM without dockerd overhead or root privileges.
  • In-Memory Micro-DNS & Service Mesh: Automatically synthesizes /etc/hosts mappings (*.local) binding services on 127.0.0.10+ without root permissions or external DNS servers.
  • Declarative Nix-to-OCI Compiler: Directly compiles container workspaces or Flakes into standardized OCI image tarballs without requiring Docker or Podman daemons (neuronix container build).
  • Transient Systemd User Quadlet Engine: Orchestrates rootless background containers and multi-service stacks natively via systemd user units (neuronix container daemon, stop, list, compose).
  • Ephemeral Multi-Service Stacks: Declaratively orchestrates multi-service stacks (--stack stack.yaml) in RAM with private IPC and millisecond startup.
  • Enterprise Credential Sanitization: Strips environment variables containing cloud tokens, SSH keys, or API credentials (AWS_*, GITHUB_*, *_TOKEN, *_KEY, SSH_AUTH_SOCK).
  • Bubblewrap Namespace Isolation: Mounts /nix/store as strictly read-only, masks $HOME with an ephemeral tmpfs, and isolates process namespaces with --clearenv, --unshare-pid, --unshare-uts, and --unshare-ipc.
  • Clean Vaporization or Export: Workspace automatically vaporizes from RAM on subshell exit (--vaporize), or optionally exports modified files back to host storage (--keep <path>).
# Launch isolated ephemeral RAM container from a remote Git repository with FHS
neuronix container https://github.com/astral-sh/uv

# Run Docker Hub container image directly in RAM without Docker daemon
neuronix container oci://alpine:latest --run "cat /etc/os-release"

# Declaratively compile workspace to standalone OCI image tarball
neuronix container build ./my-app --output app.tar --tag v1.0.0

# Run rootless container in background as a transient systemd user service
neuronix container daemon oci://nginx:alpine --name my-web
neuronix container list
neuronix container stop my-web

# Orchestrate ephemeral multi-service stack in RAM with micro-DNS service mesh
neuronix container --stack neuronix-stack.yaml

# Run command non-interactively inside the container and vaporize immediately
neuronix container https://github.com/astral-sh/uv --run "cargo test" --vaporize

# Containerize a local directory with automated export on exit
neuronix container ./my-project --keep ./my-project-output

18. Deterministic Workload Performance Matrix (neuronix tune)

Dynamically optimizes host kernel, scheduler, cgroups, and audio parameters for specific computational workloads:

  • Strict Apply-Readback-Validate Lifecycle: Eliminates silent failure masking. Every hardware control knob executes an APPLY -> READBACK -> VALIDATE loop returning truthful statuses (APPLIED, PARTIAL, UNSUPPORTED, FAILED).
  • Workload Profiles:
    • gaming: Enables high-performance CPU governor, sets EPP to performance, raises vm.max_map_count = 2147483642, optimizes thread scheduling.
    • battery: Enforces powersave CPU governor, sets EPP to power, sets 80% battery charging ceiling, engages aggressive PCIe ASPM power saving.
    • audio-daw: Configures low-latency PipeWire quantum (128 samples / 48000 Hz) for pro-audio and DAW production.
    • balanced: Restores default adaptive schedutil governors and standard desktop priorities.
  • Non-Destructive & Safe: All tunings are applied in memory and cleanly revertible without modifying persistent Nix Flakes.
# Display active CPU governors, audio latency quantum, and verified tuning status
neuronix tune --status

# Activate low-latency Pro Audio profile
neuronix tune audio-daw

# Switch to maximum performance Gaming profile
neuronix tune gaming

19. Local P2P Binary Cache Mesh (neuronix mesh)

A zero-configuration, peer-to-peer binary cache discovery mesh designed for multi-machine local networks (studios, labs, offices):

  • Native Binary Cache Serving: Integrates services.nix-serve on port 5000 with automatic firewall management and mDNS broadcasting (_nix-cache._tcp).
  • Active Peer Cache Validation: Actively probes discovered peer endpoints against /nix-cache-info before presenting or adding to substituters list, displaying verified cache status.
  • Bandwidth Conservation: Enables machines to pull pre-compiled Nix derivations directly from local peers at gigabit LAN speeds instead of re-downloading or compiling from the global Internet.
  • Decentralized & Zero-Maintenance: Requires no central Hydra server, Cachix account, or upstream credentials.
# Display binary cache mesh status, local cache server state, and active mDNS listeners
neuronix mesh status

# Discover and actively validate available peer cache nodes on the local subnet
neuronix mesh peers

# Emit discovered peers with cache verification badges in structured JSON
neuronix mesh peers --json

20. Micro Rust Systems Daemon & Live Unified AST Engine (neuronix daemon)

A standalone, high performance micro Rust systems substrate (packages/neuronix-daemon/):

  • Zero Cost Abstractions & Surgical Static Binary: Packaged as an ultra-lean 758 KB static binary compiled with zero external crates (extern crate std only), eliminating software supply chain bloat while providing microsecond response times.
  • Unified Live AST Socket (/run/neuronix/ast.sock): Exposes an authoritative Abstract System Tree (AST Schema 2.0.0) via JSON-RPC 2.0. Autonomous AI agents and tooling query active system generations, Btrfs storage topologies, memory pressure shields, and security postures through a single atomic query.
  • Fail-Safe Transparent Fallback: If executing rootless or without the binary daemon running, all queries fall back seamlessly to native Python and Bash engines with 100% functional parity.
# Display micro-Rust systems daemon status and socket health
neuronix daemon status

# Execute low-latency roundtrip ping probe
neuronix daemon ping

# Query and emit full system AST in structured JSON (Schema 2.0.0)
neuronix daemon ast

21. Ephemeral Ghost RAM Persona (neuronix ghost)

A zero-trace disposable execution mode engineered for absolute privacy and sensitive experimentation:

  • Volatile RAM Overlay (/dev/shm): Mounts an isolated tmpfs overlay in volatile memory, completely shielding host $HOME directories, SSH keys, credentials, and persistent data from untrusted execution.
  • Instant Clean Vaporization: Automatically unmounts and vaporizes volatile memory immediately upon subshell or process exit, guaranteeing 0 bytes of physical disk wear or retained digital footprints.
# Launch interactive disposable ghost shell in volatile RAM
neuronix ghost

# Execute untrusted script or test command in volatile overlay and wipe RAM on exit
neuronix ghost --run "pytest -v"

22. Instant Time Travel Workspace Branching (neuronix branch)

Brings the power of atomic operating system rollbacks down to individual project repositories:

  • Sub-Millisecond CoW Snapshots: Leverages native Btrfs subvolumes and Linux filesystem Reflinks (cp --reflink=always) to capture instantaneous point-in-time workspace checkpoints in under 10 milliseconds with 0 bytes initial storage footprint.
  • Risk-Free Prototyping: Developers and autonomous AI models can capture a checkpoint before large-scale refactorings, test modifications destructively, and restore workspace snapshots via CoW reflink if regressions are detected.
# Create an instantaneous CoW branch checkpoint of current workspace
neuronix branch create . refactor-checkpoint

# List all available branch checkpoints for this repository
neuronix branch list .

# Restore workspace from snapshot state via CoW reflink
neuronix branch revert . refactor-checkpoint

23. Declarative eBPF LSM Security Policy Gate (neuronix ebpf)

A modern Linux Security Module containment gate enforcing least-privilege security policies:

  • Kernel-Level LSM Capability Probing: Connects to Linux kernel LSM hooks via declarative security contracts (modules/security/ebpf-lsm.nix) to configure security policies outside /nix/store and /tmp.
  • Dual Operating Modes: Operates in enforcing mode (authoritative security contract for audit verification) or audit mode (advisory contract for developer telemetry).
  • Declarative Package Policies: Synthesizes custom containment policies for arbitrary packages on-demand (neuronix ebpf policy <pkg>).
# Inspect active eBPF LSM status and kernel confinement mode
neuronix ebpf status

# Generate declarative containment policy for a specific package
neuronix ebpf policy nodejs

24. Provable State Engine & Cryptographic Causal Lineage (neuronix state)

NEURONIX elevates declarative immutability into mathematical provability (NIP-0002, ADR-010):

  • 5-Leaf Merkle StateRoot: Synthesizes an authoritative SHA-256 state tree combining:
    1. hardware_posture: TPM 2.0 PCR 7 (Secure Boot) and PCR 11 (OS Unified Kernel Image / Nix closure).
    2. substrate: Active Nix store closure hash, system generation ID, and immutable stateVersion.
    3. provenance: Cryptographic causal lineage with actor identity (SO_PEERCRED UID/GID/PID) and parent transaction hash chain.
    4. policy: Declarative eBPF LSM confinement contract and active operational mode.
    5. evidence: Invariant verification results across filesystem mounts, memory shields, and security baselines.
  • RFC 8785 Canonical JSON: Zero-dependency canonical serialization ensuring bit-identical hash computation across Rust, Python, and shell engines.
  • Dual-Plane Execution: Evaluates live state via micro-Rust daemon (/run/neuronix/ast.sock via state/show and state/verify in < 2ms) with seamless fallback to pure Python neuronix_core.state.
  • Causal Lineage & Verified Recovery: Traces exact history of mutating transactions via cryptographic hash chain (prev_state_hash) and validates historical StateRoots before rollbacks.
flowchart TD
    ROOT[("5-Leaf StateRoot<br>Cryptographic Commitment")]:::rootNode
    
    ROOT --> L1["Leaf 1: Posture (L_posture)<br>TPM2 PCR Measurements & UKI"]:::leafPosture
    ROOT --> L2["Leaf 2: Substrate (L_substrate)<br>Nix Store Closure & Flake Lock"]:::leafSubstrate
    ROOT --> L3["Leaf 3: Provenance (L_provenance)<br>Actor Identity & Causal Chain"]:::leafProvenance
    ROOT --> L4["Leaf 4: Policy (L_policy)<br>Declarative eBPF LSM Contract"]:::leafPolicy
    ROOT --> L5["Leaf 5: Evidence (L_evidence)<br>Continuous Assurance & Integrity"]:::leafEvidence

    CHAIN[("Predecessor StateRoot<br>Historical State S_n-1")]:::chainNode -.->|"Cryptographic Lineage"| L3

    classDef rootNode fill:#3b1e54,stroke:#c084fc,stroke-width:3px,color:#f8fafc;
    classDef leafPosture fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef leafSubstrate fill:#1e293b,stroke:#60a5fa,stroke-width:2px,color:#f8fafc;
    classDef leafProvenance fill:#042f2e,stroke:#2dd4bf,stroke-width:2px,color:#f8fafc;
    classDef leafPolicy fill:#312e81,stroke:#a78bfa,stroke-width:2px,color:#f8fafc;
    classDef leafEvidence fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef chainNode fill:#0f172a,stroke:#94a3b8,stroke-dasharray: 5 5,stroke-width:2px,color:#cbd5e1;
Loading 
# Display live 5-leaf StateRoot commitment and component leaf hashes
neuronix state show

# Cryptographically verify the StateRoot and component invariants
neuronix state verify

# Inspect causal lineage and transaction provenance
neuronix state explain

# Compare two system states or detect drift
neuronix state diff [STATE_ROOT_A] [STATE_ROOT_B]

# View cryptographic transaction history and state chain
neuronix state history

# Verify state integrity prior to atomic recovery
neuronix state recover [STATE_ROOT]

# Export verifiable self-contained cryptographic proof bundle
neuronix state prove --output proof.json

25. Provable Adaptive Execution Architecture (Project Hyperion - neuronix run / neuronix hyperion)

NEURONIX establishes Project Hyperion (NIP-0003, ADR-011) as an adaptive execution plane wrapping proven Linux and NixOS primitives into a mathematically verifiable isolation ladder:

  • 4-Tier Adaptive Isolation Ladder: Eliminates developer overhead by automatically selecting the minimum sufficient execution boundary based on workload intent:
    1. Tier 0 (Direct Process Fast-Path): Direct CPU/GPU silicon execution with restricted seccomp filtering for trusted binaries (< 10 us launch).
    2. Tier 1 (Ephemeral RAM Ghost): Volatile tmpfs OverlayFS in /dev/shm via bubblewrap namespaces, shielding $HOME credentials with zero disk wear and instant RAM vaporization upon process exit.
    3. Tier 2 (Hardened eBPF Enclave): Ephemeral container constrained by declarative eBPF LSM syscall enforcement and cgroups v2 resource ceilings (< 25 ms launch).
    4. Tier 3 (In-Memory Micro-VM): Hermetic KVM hardware-isolated virtual machine boundary with volatile storage for untrusted workloads (< 150 ms launch).
  • Hyperion Domain Specification (HDS v1.0.0): Canonical JSON contract declaring CPU cores, memory limits, storage mounts, network airgap policies, and forbidden path boundaries.
  • Deterministic Safety Gatekeeper: Strictly rejects execution of domains targeting sensitive paths (/etc/shadow, /root, SSH/GPG keys) or invalid memory limits prior to allocation.
  • Cryptographic Domain Proof (CDP): Binds workload execution output mathematically to the host's 5-leaf StateRoot commitment, runtime evidence, and active eBPF security envelope (DomainProof = SHA-256(StateRoot || HDS_hash || Policy_hash || Output_hash || Runtime_Evidence_hash)).
flowchart TD
    INV(["User Invocation: neuronix run"]):::triggerNode --> SANITIZE["Input Sanitization<br>sys.argv & stdin Data Stream"]:::processNode
    SANITIZE --> VALIDATE["HDS Schema Validation<br>Deterministic Gatekeeper"]:::processNode
    VALIDATE --> TIER_CHECK{"Adaptive Isolation<br>Tier Selection"}:::decisionNode

    TIER_CHECK -->|"Tier 0: Fast-Path"| TIER0["Host Direct Execution<br>Silicon Native Performance"]:::tier0Node
    TIER_CHECK -->|"Tier 1: RAM Ghost"| TIER1["Bubblewrap RAM Overlay<br>Volatile tmpfs in /dev/shm"]:::tier1Node
    TIER_CHECK -->|"Tier 2: eBPF Enclave"| ENCLAVE_GATE{"bwrap Isolation<br>Available?"}:::gateNode
    TIER_CHECK -->|"Tier 3: Micro-VM"| KVM_GATE{"KVM & QEMU<br>Available?"}:::gateNode

    ENCLAVE_GATE -->|"Verified"| TIER2["Enclave Sandboxed Execution<br>Declarative eBPF LSM Bounds"]:::tier2Node
    ENCLAVE_GATE -->|"Missing"| FAIL2["FAIL-CLOSED<br>Execution Terminated (Exit 1)"]:::failClosedNode

    KVM_GATE -->|"Verified"| TIER3["Micro-VM Isolated Execution<br>Hardware Hypervisor Boundary"]:::tier3Node
    KVM_GATE -->|"Missing"| FAIL3["FAIL-CLOSED<br>Execution Terminated (Exit 1)"]:::failClosedNode

    TIER0 --> PROOF["Cryptographic Domain Proof<br>Workload & Runtime Evidence Binding"]:::proofNode
    TIER1 --> PROOF
    TIER2 --> PROOF
    TIER3 --> PROOF

    PROOF --> JCS["RFC 8785 Canonical Serialization<br>Deterministic JCS Encoding"]:::proofNode
    JCS --> ROOT[("5-Leaf StateRoot Attestation<br>Mathematical Workload Receipt")]:::stateNode

    classDef triggerNode fill:#0f172a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef processNode fill:#1e293b,stroke:#94a3b8,stroke-width:1.5px,color:#f8fafc;
    classDef decisionNode fill:#1e1e38,stroke:#818cf8,stroke-width:2px,color:#f8fafc;
    classDef gateNode fill:#2e1065,stroke:#a855f7,stroke-width:2px,color:#f8fafc;
    classDef tier0Node fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef tier1Node fill:#042f2e,stroke:#2dd4bf,stroke-width:2px,color:#f8fafc;
    classDef tier2Node fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc;
    classDef tier3Node fill:#312e81,stroke:#a78bfa,stroke-width:2px,color:#f8fafc;
    classDef failClosedNode fill:#881337,stroke:#f43f5e,stroke-width:2px,color:#f8fafc;
    classDef proofNode fill:#262626,stroke:#cbd5e1,stroke-width:1.5px,color:#f8fafc;
    classDef stateNode fill:#3b1e54,stroke:#c084fc,stroke-width:3px,color:#f8fafc;
Loading 
# Execute workload with automatic intent-based tier negotiation
neuronix run --intent "untrusted python script" python3 untrusted.py

# Execute command in Tier 1 volatile RAM overlay with cryptographic domain proof
neuronix run --ephemeral --proof /bin/uname -a

# Negotiate and inspect canonical HDS domain spec without executing
neuronix run --dry-run --intent "ai agent task" python3 -V

# Display Hyperion Execution Plane telemetry and tier capabilities
neuronix hyperion status

# Negotiate domain contract for a workload
neuronix hyperion negotiate compiler-job --tier 1

# Verify cryptographic DomainProof mathematically against StateRoot
neuronix hyperion verify [DOMAIN_ID]

# Enumerate executed domain receipts and proof roots
neuronix hyperion list

26. Verification Passport & Zero-Dependency Offline Verifier (neuronix verify-passport)

To satisfy the engineering principle of maximum epistemic trust per line of code, NEURONIX OS introduces the Verification Passport & Offline Verifier Architecture. Instead of relying on vendor assurances or online authority servers, every release, commit, and state transition can be audited, falsified, and mathematically verified completely offline with zero third-party dependencies.

flowchart TD
    A["Authoritative Test Harness (1,384 Assertions)"] --> B["Evidence Compiler (tools/compile_evidence.py)"]
    C["5-Leaf Merkle StateRoot Engine"] --> B
    D["Golden Host Matrix (8 Hardware Profiles)"] --> B
    B --> E["Verification Passport (dist/verification-passport.json)"]
    E --> F["Zero-Dependency Offline Verifier (tools/verify_passport.py)"]
    E --> G["Integrated CLI (neuronix verify-passport)"]
    H["Negative Reproducibility Gate (6 Mutants)"] -.->|Falsifiability Audit| E
    I["Differential Fuzzer (Python vs Node.js vs Rust)"] -.->|Bit-Exact Parity| C
Loading

Core Components & Architectural Invariants:

  1. Authoritative Evidence Compiler (tools/compile_evidence.py): Aggregates all 1,384 system assertions across 32 QA master suites, 19 distro suites, and 25 standalone verification gates into a multi-tier taxonomy:

    • CATALOG: 1,384 registered system assertions with suite boundaries and test categories.
    • VERIFIED: 1,384 verified assertions with zero unverified regressions.
    • OBSERVED: Live hardware and kernel capability probes (KVM virtualization, Bubblewrap, cgroups v2, eBPF LSM).
    • ATTESTED: SLSA Level 3 keyless build provenance and GPG detached release signatures. Computes a deterministic canonical SHA-256 digest (data/assurance_evidence_snapshot.json) bound directly into L_evidence of the 5-leaf Merkle StateRoot.

  2. Verification Passport Specification (dist/verification-passport.json): A self-contained release passport formatted in RFC 8785 ECMAScript 5.1 canonical JSON. The passport specifies:

    • Target Release Version and Commit SHA lineage.
    • 5-Leaf Merkle StateRoot cryptographic commitment.
    • Comprehensive assertion catalog and test results.
    • Golden Host Reference Matrix across all 8 certified hardware platforms.
    • Detached SHA-256 passport digest ensuring tamper-free distribution.

  3. Zero-Dependency Offline Verifier (tools/verify_passport.py): A standalone single-file Python engine requiring only the standard library (Python 3.8+). It embeds an independent RFC 8785 canonical serializer, parses detached passport digests, and validates Merkle StateRoot commitments without internet access, third-party packages, or background daemons.

  4. Integrated CLI Command (neuronix verify-passport): Exposes the offline verification engine directly through the system CLI dispatcher for immediate operator validation.

  5. System Doctor Proof Mode (neuronix doctor --proof): Extends system diagnostics to emit an authoritative SystemVerificationReceipt JSON payload cryptographically bound to the active StateRoot, hardware PCR state, JCS conformance vectors, and an 8-dimensional trust_vector (posture, substrate, policy, evidence, runtime, provenance, freshness, overall).

# Verify official release passport offline with zero dependencies
neuronix verify-passport dist/verification-passport.json

# Run standalone verifier in any clean Python environment
python3 tools/verify_passport.py dist/verification-passport.json

# Generate authoritative SystemVerificationReceipt with cryptographic proof
neuronix doctor --proof

# Recompile canonical evidence snapshot & generate Verification Passport
python3 tools/compile_evidence.py

27. Authoritative Evidence Graph & Lineage Traversal (neuronix graph)

NEURONIX OS structures all epistemic guarantees into an authoritative 18-node Directed Acyclic Graph (DAG) connecting foundational source code to verifiable release artifacts:

  • 18-Node Universal Control Plane Topology:
    1. SOURCE_NODE: Authoritative Git commit SHA, branch identity, and governance source anchor.
    2. BUILD_NODE: Substrate build derivation binding parent source commit, Flake lock hash, and system store path.
    3. HARDWARE_NODE: Portable hardware facter leaf ($L_{\text{hardware}}$) capturing CPU topology, virtualization, and firmware contracts.
    4. TOPOLOGY_NODE: System topology graph leaf ($L_{\text{topology}}$) validating acyclic component hierarchies.
    5. CAPABILITY_NODE: Security capability and namespace confinement leaf ($L_{\text{capability}}$).
    6. POLICY_NODE: Evaluated security policy leaf ($L_{\text{policy}}$) compiling eBPF LSM rules and sandboxing bounds.
    7. STORAGE_NODE: Storage planner and Btrfs subvolume layout leaf ($L_{\text{storage}}$).
    8. BOOT_NODE: Measured boot and Secure Boot telemetry leaf ($L_{\text{boot}}$).
    9. SECRETS_NODE: Capability-bound ephemeral secret fabric leaf ($L_{\text{secrets}}$).
    10. LIFECYCLE_NODE: State lifecycle preservation and generational tier distribution ($L_{\text{lifecycle}}$).
    11. STATE_NODE: 5-Leaf Merkle StateRoot commitment binding all leaf domain roots.
    12. RUNTIME_NODE: Authoritative runtime receipt verifying backend execution, nonce freshness, and exit codes.
    13. TEST_NODE: Industrial assurance verification node binding test manifest hash, 1,384 executed assertions, and CI run ID.
    14. RELEASE_NODE: Qualified release root concatenating target commit SHA, parent build digest, StateRoot, and test digest.
    15. HOST_NODE: Hardware attestation contract compatibility alias.
    16. HDS_NODE: Hierarchical domain specification compatibility alias.
    17. OUTPUT_NODE: Workload output artifact digest compatibility alias.
    18. PROOF_NODE: Domain proof attestation contract compatibility alias.
  • Strict Cryptographic Parent Edges: Every child node references its authoritative parent digests. If any upstream leaf or source code is altered, downstream edge hashes diverge, invalidating the graph.
  • Directed Lineage Traversal (--trace): Operators and automated verifiers can trace backward lineage from any target node (e.g., --trace release or --trace proof) all the way back to SOURCE_NODE, verifying cryptographic integrity at every edge.
  • Integrated Visualization: Visualizes graph topology natively in formatted ASCII trees or Graphviz DOT notation (neuronix graph --format ascii or neuronix graph --format dot).
flowchart TD
    SOURCE["1. SOURCE_NODE<br>Git Commit SHA & Source Anchor"]:::rootNode --> BUILD["2. BUILD_NODE<br>Substrate Derivation Proof"]:::midNode
    
    HARDWARE["3. HARDWARE_NODE<br>Hardware Intelligence"]:::midNode --> STATE["11. STATE_NODE<br>5-Leaf Merkle StateRoot"]:::stateNode
    TOPOLOGY["4. TOPOLOGY_NODE<br>System Topology DAG"]:::midNode --> STATE
    CAPABILITY["5. CAPABILITY_NODE<br>Capability Boundary"]:::midNode --> STATE
    POLICY["6. POLICY_NODE<br>Security Policy Leaf"]:::midNode --> STATE
    STORAGE["7. STORAGE_NODE<br>Storage Planner Root"]:::midNode --> STATE
    BOOT["8. BOOT_NODE<br>Measured Boot Trust"]:::midNode --> STATE
    SECRETS["9. SECRETS_NODE<br>Ephemeral Secret Fabric"]:::midNode --> STATE
    LIFECYCLE["10. LIFECYCLE_NODE<br>Lifecycle Preservation"]:::midNode --> STATE
    
    BUILD --> STATE
    HARDWARE --> CAPABILITY
    CAPABILITY --> RUNTIME["12. RUNTIME_NODE<br>Runtime Receipt Hash"]:::midNode
    STATE --> RUNTIME
    RUNTIME --> TEST["13. TEST_NODE<br>1,384 Assertions Manifest"]:::midNode
    
    BUILD --> RELEASE["14. RELEASE_NODE<br>Proof-Carrying Release Root"]:::releaseNode
    TEST --> RELEASE
    PROOF["18. PROOF_NODE<br>DomainProofV1 Contract"]:::midNode --> RELEASE

    classDef rootNode fill:#0f2744,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef midNode fill:#1e293b,stroke:#94a3b8,stroke-width:1.5px,color:#f8fafc;
    classDef stateNode fill:#3b1e54,stroke:#c084fc,stroke-width:3px,color:#f8fafc;
    classDef releaseNode fill:#064e3b,stroke:#34d399,stroke-width:3px,color:#f8fafc;
Loading 
# Render complete 18-node authoritative evidence graph in terminal
neuronix graph

# Render graph in structured ASCII tree format
neuronix graph --format ascii

# Render graph in Graphviz DOT format
neuronix graph --format dot

# Trace cryptographic backward lineage for production release bundle
neuronix graph --trace release

# Trace lineage specifically for canonical domain proof
neuronix graph --trace proof

# Emit graph structure in machine-readable JSON format
neuronix graph --json

28. Canonical Domain Proof Specification & Dual Plane Parity (SPEC-NRX-DP-014)

To eliminate any discrepancy between high-level Python tooling and low-level systems runtimes, NEURONIX OS establishes the Canonical Domain Proof Specification (SPEC-NRX-DP-014):

  • Canonical 6-Part Merkle Commitment: $$P_{\text{root}} = \operatorname{SHA-256}(L_{\text{state}} \parallel H_{\text{hds}} \parallel H_{\text{policy}} \parallel H_{\text{input}} \parallel H_{\text{output}} \parallel H_{\text{receipt}})$$ Where $H_{\text{receipt}} = \operatorname{SHA-256}(\operatorname{JCS}(\text{RuntimeReceipt}))$, binding workload identity, isolated environment metadata, and execution nonces.
  • Bit-Exact Cross-Language Implementation: The micro-Rust daemon (packages/neuronix-daemon/src/hyperion.rs) and Python core engine (packages/neuronix-core/neuronix_core/hyperion.py) implement the identical RFC 8785 canonical JSON encoder and SHA-256 hashing logic. Differential fuzzing verifies 100% bit-for-bit parity across both implementations.
  • Fail-Closed Decision Tree: Eliminates hardcoded trust verdicts. The verification engine evaluates proofs through strict deterministic validation:
    1. NO_RUNTIME_RECEIPT: Missing or null execution receipt results in immediate mathematical invalidation (mathematical_validity: false).
    2. ISOLATION_EVIDENCE_MISMATCH: Execution backend or runtime mode does not satisfy the declared tier requirement (e.g. Tier 3 requested but hardware hypervisor absent).
    3. EXECUTION_ANOMALY: Non-zero exit code or anomalous termination produces verdict EXECUTION_ANOMALY.
    4. UNTRUSTED_HOST_POSTURE: Missing TPM measurements or unverified host state produces UNTRUSTED_HOST_POSTURE.
    5. VERIFIED_TRUSTED: Issued strictly when all mathematical, isolation, and execution invariants evaluate to green.
# Generate canonical DomainProofV1 via Python engine
python3 -c "from neuronix_core.hyperion import HyperionEngine; h = HyperionEngine(); print(h.generate_canonical_domain_proof('domain-001'))"

# Generate canonical DomainProofV1 via micro-Rust systems daemon
neuronix-daemon --hyperion proof '{"domain_id": "domain-001"}'

# Verify domain proof via micro-Rust daemon
neuronix-daemon --hyperion verify '{"domain_id": "domain-001", "proof_root": "..."}'

29. Continuous Security Invariant Registry (SEC-001 to SEC-020)

System security in NEURONIX OS is governed by a formal invariant registry (SPEC-NRX-SEC-015, data/security_invariants/registry.json). Every invariant is verified by automated gate tests/test_security_invariants.sh:

ID Invariant Name Enforcement Mechanism Scope Status
SEC-001 Flake Channel Immutability Pure locked revision matching version.nix and flake.lock Supply Chain VERIFIED
SEC-002 Nix Store Immutability Read-only bind-mount and bubblewrap isolation Filesystem VERIFIED
SEC-003 Cryptographic Nonce Freshness Monotonic execution nonces, replay rejection Hyperion VERIFIED
SEC-004 Deterministic JCS Serialization Strict RFC 8785 canonical encoding with ES5.1 numbers Cryptography VERIFIED
SEC-005 Fail-Closed Hypervisor Boundary Tier 3 rejects execution when KVM unavailable Isolation VERIFIED
SEC-006 Zero Mocks In Production Path Synthetic flags forbidden in live release builds Runtime VERIFIED
SEC-007 eBPF LSM Confinement Integrity Security hooks enforce least-privilege policies Kernel VERIFIED
SEC-008 Evidence Graph Directed Lineage 18-node DAG with tamper-proof parent hashes Epistemics VERIFIED
SEC-009 Verification Passport Tamper Proof Self-contained offline validation rejects corrupt digests Release VERIFIED
SEC-010 Cross-Language Cryptographic Parity Python and micro-Rust produce identical proof roots Dual-Plane VERIFIED
SEC-011 Capability-Bound Resource Guard Memory, CPU, and network quotas enforced fail-closed Resource VERIFIED
SEC-012 7-Factor Storage Destructive Firewall Active generation and mount lockout with typed token Storage VERIFIED
SEC-013 Plaintext Secret Omission StateRoot and EvidenceGraph contain zero plaintext data Secrets VERIFIED
SEC-014 AI Secret Visibility Isolation Copilots and LLM actors receive metadata only AI-Gov VERIFIED
SEC-015 Sequential Boot Health Contract Monotonic 5-stage health progression before LKG commit Boot VERIFIED
SEC-016 Hardware Attestation Integrity Facter root cryptographically anchored into StateRoot Hardware VERIFIED
SEC-017 Read-Only System Probing Fact collection guarantees non-mutating observability Telemetry VERIFIED
SEC-018 Universal Topology DAG Causality Effective topology with Kahn cycle detection Topology VERIFIED
SEC-019 AI Proposal Proposer-Only Boundary Autonomous transitions require preflight simulation Governance VERIFIED
SEC-020 Decoupled State & Evidence Identity StateRoot and EvidenceRoot decoupled and authentic Cryptography VERIFIED 
# Execute automated security invariant verification gate (20/20 invariants)
bash tests/test_security_invariants.sh

30. Proof-Carrying Release Architecture (dist/neuronix-os-v1.0.5.proof.json)

NEURONIX OS implements Proof-Carrying Release (PCR) bundles, coupling release media directly with cryptographic verification tokens:

  • Unified Release Bundle (dist/neuronix-os-v1.0.5.proof.json): Packages the canonical release metadata:
    • Canonical Release Tag (v1.0.5) and Git Commit SHA.
    • Live ISO Image SHA-256 digest (dist/neuronix-os-1.0.5-x86_64.iso).
    • Software Bill of Materials (SBOM) digest (dist/neuronix-os-v1.0.5-sbom.spdx.json).
    • Authoritative 5-leaf Merkle StateRoot.
    • Verification Passport Digest (dist/verification-passport.json).
    • Directed Evidence Graph Digest (dist/evidence-graph.json).
    • Complete 18-node evidence graph snapshot.
  • Offline Self-Verification (neuronix verify-release): Third-party auditors, users, and automated staging gates verify the complete supply chain offline in a single command, ensuring zero bit-level tampering from source code to installation media.
# Generate the official proof-carrying release bundle
python3 tools/generate_release_proof.py

# Verify the proof-carrying release bundle against ISO image and evidence graph
neuronix verify-release dist/neuronix-os-v1.0.5.proof.json

# Offline verification without neuronix CLI installation
python3 tools/verify_passport.py dist/neuronix-os-v1.0.5.proof.json

31. Closed Semantic Subsystem Architecture (MES-NRX-002)

Following the v1.0.4 audit cycle, NEURONIX OS fully transitioned from mock or static evaluation models into 100% closed, production-grade semantic enforcement across 5 core subsystems and standalone verification:

  1. Secret Execution Engine (neuronix_core.secrets):

    • Authentic Age encryption and decryption envelopes using official age CLI wrapping (age or rage), standard X25519 identities (AGE-SECRET-KEY-1...), and public recipients (age1...) formatted in standard ASCII armor (-----BEGIN AGE ENCRYPTED FILE-----).
    • Volatile in-memory storage verification (tmpfs/ramfs) via /proc/mounts, preventing unencrypted disk leakage.
    • Strict security invariants: MISSING_AGE_IDENTITY fail-closed when key is missing, CAPABILITY_MISMATCH fail-closed when capability token does not authorize path, zero plaintext in StateRoot, and zero partial secret residue on failure.
    • AI metadata masking ([MASKED: AI_SECRET_VISIBILITY_METADATA_ONLY]) enforcing strict visibility separation (SEC-014).

  2. Storage Safety Firewall (neuronix_core.storage_planner):

    • 7-Factor destructive operation evaluation (SEC-012):
      • Factor 1: Physical Device Identity verification.
      • Factor 2: Active Mount Lockout inspecting /proc/mounts against critical filesystems.
      • Factor 3: Active Generation Safety discovering backing devices for active NixOS profiles and kernel command line.
      • Factor 4: Existing Filesystem Entropy and signature check.
      • Factor 5: Preflight Simulation Clearance simulating partition geometry, LBA 2048 alignment, and Btrfs subvolumes.
      • Factor 6: Exact-Match Typed Confirmation Token (DESTROY <dev> PLAN <64char_plan_hash>).
      • Factor 7: Operator Identity & Cryptographic Clearance (STORAGE_ADMIN or DISASTER_RECOVERY_OPERATOR via Ed25519 asymmetric cryptographic signatures and replay protection nonces).
    • Transactional postcondition verification confirming physical layout matches planned specifications.

  3. Boot Health Contract (neuronix_core.boot_trust):

    • Multi-stage monotonic state machine (KERNEL_REACH -> MOUNTS_HEALTHY -> DAEMON_READY -> STATE_VERIFIED -> DESKTOP_TARGET). Out-of-order transitions trigger fail-closed rollback (SEC-015).
    • Observable host telemetry probing /proc/version, /proc/mounts, runtime sockets, and systemd targets.
    • Empirical 5-tier recovery mechanism detection (LUKS key slot fallback, dual-key MOK, LKG generation rollback, sentinel watchdog, and hermetic fallback boot binary).

  4. Semantic AI Governance Engine (neuronix_core.semantic):

    • Upstream nix-instantiate --parse integration with offline lexical bracket-matching fallback parser.
    • Grounded canonical option registry (CANONICAL_OPTIONS) with strict type checking (boolean, integer, string, allowed values).
    • Proposer-Only enforcement rejecting direct commits (SEC-019) and prohibiting security baseline bypasses.
    • Declarative dry-run configuration diff generation with isolated blast-radius classification.

  5. Universal Live System Topology (neuronix_core.topology):

    • Live system observation probing active mount namespaces, network interfaces, and daemon IPC sockets.
    • Effective topology convergence combining canonical architectural specifications with live telemetry (CONVERGED, CANONICAL, OBSERVED).
    • Kahn's algorithm cycle detection and differential blast radius calculation (declared_affected_nodes vs observed_affected_nodes).

  6. Zero-Dependency Standalone Verifier (tools/verify_passport.py):

    • Embedded RFC 8785 JSON Canonicalization Scheme (JCS) serializer with strict UTF-16 code-unit key sorting and ECMAScript 5.1 number formatting.
    • Cryptographic DAG verification validating individual domain commitment roots (hardware_root, topology_root, storage_root, boot_trust_root, secret_root, state_root, etc.).
    • Topological acyclic validation via Kahn's algorithm and backward lineage reachability tracing (RELEASE_NODE -> SOURCE_NODE).
# Execute comprehensive semantic closure test suite (37 tests)
python3 tests/test_semantic_closure.py -v

32. Conductor Operating Surface & Zero-Idle Capability Runtime (SPEC-NRX-CND-018, SPEC-NRX-CND-021)

NEURONIX Conductor is the native operating surface and local agent substrate for the NEURONIX platform. Conductor replaces visual complexity with a single, terminal-first window offering maximum capability and zero permanent clutter:

  • Surface Architecture: One unified window featuring a 95% workspace canvas dedicated to an ultra-fast, native Rust terminal subsystem (packages/conductor). A subtle topbar displays CONDUCTOR [ NEURONIX v1.0.5:gen-X ] alongside live Vital health status (VITAL o NOMINAL) and adaptive workspace tabs:
    • Tab 1: Terminal - Full-speed VT100 terminal canvas with 95% screen real estate.
    • Tab 2: Vital - Real-time machine observation laboratory with CPU, memory, mount, and StateRoot telemetry.
    • Tab 3: Proposals - Dedicated deck for reviewing and resolving pending mutation proposals.
    • Tab 4: Capabilities - Live catalog of registered skills categorized into mutation and inspection gates.
  • Terminal Emulator Subsystem: High-performance VT100/ANSI state machine featuring full SGR color styling, cursor tracking, scrollback history, alternate screen buffer support, and POSIX PTY process management via pty.rs (TIOCSWINSZ window resizing and signal propagation).
  • Zero-Idle Runtime Broker (packages/conductor-runtime): Operates on an on-demand socket activation lifecycle (systemd/user/conductor.socket listening on $XDG_RUNTIME_DIR/conductor.sock with 0600 permissions):
    • COLD: 0 connected clients, 0% CPU overhead, near-zero resident footprint (socket managed by systemd). Target budget under 15 MB RSS when active.
    • WARM: External agents, MCP servers, or CLI tools connected via socket, executing capabilities with low-latency responsive IPC and zero GUI process overhead.
    • HOT: Visual desktop surface attached with interactive rendering overlays.
  • Ephemeral Proposal Overlays: When an operation requires human review, Conductor slides in a non-disruptive, structured proposal card displaying the title, risk tier, parameter diff, and cryptographic proposal hash without breaking terminal workflow. Operators can interactively approve ([y]), reject ([n]), or dismiss ([Esc]) proposals in real time.

33. Vital Laboratory Observation Substrate & Machine Contracts (SPEC-NRX-VTL-020)

Vital is the canonical observation provider and laboratory telemetry substrate for humans and AI interfaces, adhering to the fundamental doctrine: "No Consumer, No Work".

  • Four Telemetry Classes:
    • OBSERVED: Ground-truth hardware and kernel metrics sampled directly from /proc, /sys, hwmon, and statvfs.
    • DERIVED: Deterministic calculations (such as memory pressure or filesystem utilization percentages) tagged with explicit confidence scores (0.0 to 1.0).
    • EVENT: Discrete state transitions, lifecycle events, and audit logs bound to monotonic time.
    • DIAGNOSTIC: Anomaly detections, throttling alerts, and degraded posture indicators.
  • The Invariant "Unknown Must Remain Unknown": Vital strictly prohibits synthetic heuristic fallbacks (such as guessing missing temperatures as 45.0 degrees Celsius). If a sensor is unexposed or unreadable, the metric evaluates strictly to null with availability="UNAVAILABLE" and an explicit audit reason.
  • Laboratory-Grade Precision: Every telemetry record carries UTC ISO 8601 timestamps, monotonic nanosecond clock readings (monotonic_at), data currency ratings (freshness_ms), and cryptographic provenance tags (nrx-vtl:...).

34. NEURONIX Skill System & Delegated Authority Engine (SPEC-NRX-SKL-019)

The NEURONIX Skill System establishes a single, authoritative machine-readable operating manual for every system capability across CLI, Conductor GUI, and MCP interfaces:

  • Canonical Skill Contracts: All system capabilities (system.status, vital.snapshot, system.rollback, storage.plan, state.verify, system.upgrade, boot.verify, hyperion.run, package.verify, daemon.status, topology.observe) are formalized as declarative contracts in data/skills/*.json validated against data/schemas/skill_contract.schema.json. Execution is unified via the canonical skills.invoke pipeline.
  • User Sovereignty & Delegated Authority:
    • The human owner retains supreme sovereign authority over the system. Guardrails inform of blast radius and recovery paths rather than paternalistically blocking the owner.
    • sudo is explicitly recognized as a valid privileged capability under human ownership.
    • 5-Tier Delegated Authority for AI agents: OBSERVE_ONLY, PROPOSE_ONLY, USERSPACE_EXECUTE, PRIVILEGED_EXECUTE, and FULL_DELEGATED_CONTROL.
    • Strict Token-Validated Authority: Self-asserted delegation claims from unauthenticated agents are rejected fail-closed. Valid execution requires an authentic delegation grant token (DEL-...) issued by the human owner with explicit scope and time expiry.
  • Unbypassable Audit Trail: Every skill execution generates an immutable cryptographic execution receipt (RCP-...) recording SHA-256 input digests, output digests, caller principal, delegation tier, duration, and execution timestamp.
  • Model Context Protocol (MCP) Adapter (packages/conductor-mcp): Native compatibility adapter supporting both modern MCP 2026-07-28 and legacy 2024-11-05 specifications, translating external agent tool calls directly into verified NEURONIX skills and exposing Vital telemetry as laboratory resources (vital://snapshot).

35. Universal Operational Environment (UOE) & Execution Fabric

NEURONIX OS evolves from traditional operating system assumptions into a Universal Operational Environment (UOE), unifying the Universal Execution Fabric (UEF) and the Operational Semantic Layer (OSL):

  • Universal Operational Semantic Overlay: Linux and NixOS provide the certified, deeply integrated host substrate. NEURONIX adds universal typed operational semantics to system operations: intent, actor, authority, environment, preconditions, expected effects, security invariants, evidence, and outcome.
  • Operational Contract Envelope (OCE): All operational actions are formalized via canonical Draft 2020-12 schemas (data/schemas/operational_contract_envelope.schema.json) and canonicalized with RFC 8785 JSON Canonicalization Scheme (JCS).
  • Dynamic Multi-Factor Provider Scoring: ProviderResolver scores execution providers dynamically using empirical capability vectors: $$Score = C_{compat} \times (0.25 P_{policy} + 0.25 I_{isolation} + 0.20 R_{resource} + 0.20 L_{latency} + 0.10 Q_{provenance})$$
  • Hardened Fail-Closed Execution Providers:
    • native.linux: 0% overhead host POSIX execution with direct syscall performance.
    • rootfs.bwrap: Unprivileged Bubblewrap sandbox for foreign rootfs directories. Fails closed (compatible = False) when bwrap is missing; captures authentic stderr and non-zero exit codes.
    • oci.crun: Strictly orthogonal two-mode OCI provider. Mode A (oci-image) strictly requires high-level engines (podman/docker) and rejects low-level runtimes; Mode B (rootfs-dir, oci-bundle) strictly requires low-level runtimes (crun/runc), rejecting high-level engines, while validating config.json specifications and rootfs directory integrity. Incompatible execution calls fail closed with RuntimeError.
  • Pure-Python Ed25519 Cryptographic Delegation: AI agent mutations require valid delegation tokens digitally signed and verified via pure-Python RFC 8032 Ed25519 cryptography across principal identity, action scope, delegation tier, expiration timestamp, and anti-replay input digest. Unexecutable actions fail closed with CoherenceUnexecutableError.
  • Fail-Closed StateRoot Post-State Verification: All provider receipts record live state root queries. Failed state computations emit "UNVERIFIED", causing Tier 2 mutations to abort with CoherenceStateRootError.
  • Empirical Latency & Zero-Leak Multi-Provider Endurance:
    • Resolver & Coherence Latency: Median 269 us dynamic resolution scoring; median 3.04 us envelope policy evaluation.
    • 1,000-Cycle Endurance Qualification (Native + Rootfs): 1,000 full execution lifecycles verified with 0 FD leaks, 0 mount leaks, 0 leftover temporary directories, and 0.31 MB bounded RSS delta.
    • 100-Cycle OCI Container Qualification: 100 full container bundle preparation and cleanup lifecycles verified with 0 FD leaks, 0 mount leaks, 0 leftover temporary directories, and 0.01 MB RSS delta (1.05 ms/cycle).
  • The 8 Lean Architecture Rules: Zero idle execution daemons, no unnecessary virtual machines, ephemeral memory cleanup on exit, lean ISO distribution footprint, and native path preservation.

36. Hardware Qualification & Truthful L5 Hypervisor Reservation (NRX-SPEC-022)

NEURONIX OS distinguishes between portable software contracts verified across automated continuous integration pipelines and physical bare-metal execution (NRX-SPEC-022):

  • Epistemic Honesty & Zero-Simulation Policy: In containerized or virtualized runner environments lacking hardware virtualization (/dev/kvm), NEURONIX strictly prohibits simulated or fraudulent L5 pass assertions. If physical prerequisites are missing, execution is truthfully recorded as an unsimulated L4 verification contract.
  • Mandatory L5 Hardware Prerequisites: Full L5 execution requires 5 physical parameters: (1) read-write /dev/kvm character device, (2) CPU hardware virtualization extensions (vmx or svm), (3) minimum 4 GiB unreserved host RAM, (4) minimum 15 GiB dedicated block storage, and (5) staged live installation ISO (dist/neuronix-os-1.0.5-x86_64.iso).
  • Golden Reference Hardware Matrix (data/hardware_qualification.json): Formally catalogs 8 platform profiles across 5 qualification tiers, including maintainer bare-metal reference workstations (amd-workstation-rdna3, Ryzen 9 7950X, Radeon RX 7900 XTX, BARE_METAL_TESTED), virtualized hypervisors (qemu-kvm-microvm, VM_VALIDATED), and targeted laptop/workstation profiles (lenovo-thinkpad-t14, framework-laptop-13, intel-workstation-arc, dell-xps-15-hybrid).

37. Longitudinal Reliability & Multi-Cycle Soak Testing Protocol (NRX-SPEC-023)

To ensure that long-running control planes, background daemon processes, and AI agent execution environments do not degrade over sustained multi-day or multi-week operation, NEURONIX OS establishes formal longitudinal reliability specifications (NRX-SPEC-023):

  • Resource Invariant Preservation Gates: Asserts zero unclosed file descriptors (INV-RES-001_ZERO_FD_LEAK: $\Delta FD == 0$), zero leaked kernel mount points (INV-RES-002_ZERO_MOUNT_LEAK: $\Delta Mount == 0$), zero leftover scratch directories in volatile memory (INV-RES-003_ZERO_TEMP_DIR_LEAK: $\Delta Temp == 0$), and strictly bounded resident set size growth (INV-RES-004_BOUNDED_RSS_GROWTH: $\Delta RSS &lt; 1.0\text{ MB}$ over 1,000 cycles).
  • 1,000-Cycle Endurance Qualification Matrix (benchmark_uef_resources.py): 1,000 full execution lifecycles completed in 13.7 seconds (13.7 ms/cycle) with 0 FD leaks, 0 mount leaks, 0 temp dir leaks, and 0.33 MB RSS delta.
  • 100-Cycle OCI Container Soak Benchmark: 100 continuous container prepare, execution, and cleanup cycles completed in 0.04s (0.387 ms/cycle) with zero resource leaks and 0.01 MB RSS growth.
  • 100-Iteration Generation Rollback Benchmark: 100 atomic profile switches (Gen 42 -> 41 -> 40) verified with sub-millisecond p99 latency (0.047 ms) and zero state corruption.

38. Cryptographic Trust Anchor & Release Signature Verification

NEURONIX OS release tags and binary distributions are cryptographically signed using the maintainer's primary EdDSA GPG key:

  • Maintainer GPG Signing Key: dist/MAINTAINER_GPG_KEY.asc (also available at docs/security/MAINTAINER_GPG_KEY.asc)
  • Key Fingerprint: 92C6CCCAA701EB18DE678D4B0DEEDA0E9629F4D3
  • Signer Identity: adamriofc <adamriofc@protonmail.com>
  • Independent Offline Verification: Any developer or security auditor can verify official signed release tags directly using standard GnuPG: 
    # Import maintainer public key into local keyring
gpg --import dist/MAINTAINER_GPG_KEY.asc

# Verify cryptographic signature on release tag
git tag -v v1.0.5
  • GitHub Identity & Web UI Badge Behavior: On the GitHub web interface, commit and tag signatures display a green "Verified" badge if and only if the signing public key has been registered to the author's GitHub user account (https://github.com/settings/keys). When auditing release tags locally via GnuPG, the signature is cryptographically valid, authentic, and tamper-free regardless of third-party web interface trust stores.

Building & Installation

Building the Installation Medium

To compile the official Live ISO installer image directly from source:

git clone https://github.com/adamriofc/NeuronixOS.git
cd NeuronixOS

# Option 1: Automated ISO utility with integrity hashing
./scripts/build_iso.sh

# Option 2: Direct Flake build
nix build .#packages.x86_64-linux.iso --out-link result-iso

The resulting bootable image is located at dist/neuronix-os-1.0.5-x86_64.iso (or result-iso/iso/neuronix-os-*.iso). Flash to installation media:

sudo dd if=dist/neuronix-os-1.0.5-x86_64.iso of=/dev/sdX bs=4M status=progress oflag=sync

High Performance Binary Caching

NEURONIX incorporates continuous binary caching across GitHub Actions workflows and local environments:

  • Upstream Cache: https://cache.nixos.org (NixOS hydra channels)
  • Community Cache: https://nix-community.cachix.org (Nix community packages)
  • Continuous CI Cache: Powered by Determinate Systems Magic Nix Cache for instant sub-minute builds without recompilation.

Installation Workflow

  1. Boot the target system from the live installation medium (boots directly into live GNOME session via automated GDM autologin).
  2. Select driver initialization mode (standard open-source drivers or proprietary NVIDIA drivers).
  3. The Calamares installer starts automatically within the Wayland graphical desktop session.
  4. Select a partitioning scheme (automated Btrfs ZSTD:3 layout or manual partition mapping).
  5. Configure regional settings, user credentials (provisioned via declarative users.conf), and desktop environment (KDE Plasma, GNOME, or Hyprland).
  6. Complete declarative target installation via neuronix-install-engine and reboot into the target environment.

Post Installation Administration

Modifying System Configuration

The installed system is configured declaratively in /etc/nixos/:

# Edit host configuration
sudo nano /etc/nixos/configuration.nix

# Rebuild and activate new system generation atomically
sudo nixos-rebuild switch --flake /etc/nixos#neuronix-desktop

Managing Application Packages

  • CLI tools: Add package names to environment.systemPackages in configuration.nix.
  • Graphical applications: Install sandboxed applications via KDE Discover or GNOME Software using Flathub:
flatpak install flathub com.spotify.Client
flatpak install flathub org.videolan.VLC

Reclaiming Storage

To run a manual storage optimization cycle:

neuronix diet

Verification, Lifecycle Gate & Industrial Test Battery (1,384 Assertions)

System invariants, module structures, and CLI dispatchers are validated through an automated test battery comprising 1,384 automated assertions across 25 standalone gates (32 master suites, 19 distro suites, and 25 standalone gates):

═══════════════════════════════════════════════════════════════════
                    TEST HARNESS REPORT SUMMARY                    
═══════════════════════════════════════════════════════════════════
  Master Test Harness (tests/run_all_tests.sh)     : 899 / 899 PASS
  Distro Test Harness (tests/test_distro_suite.sh) : 209 / 209 PASS
  Single Source of Truth Gate (source_of_truth)    :  13 /  13 PASS
  Multi-Architecture Matrix (multiarch_matrix)     :  13 /  13 PASS
  Two-Build Derivation Repro (two_build_repro)     :   8 /   8 PASS
  Hybrid E2E ISO Lifecycle Gate (e2e/test_iso_install):  8 /   8 PASS
  Real OS Install & Boot Gate (test_real_os_install_boot): 10 /  10 PASS
  Release Lifecycle Gate (test_release_lifecycle)  :  46 /  46 PASS
  Multi-Hop Rollback Correctness (rollback_corr)   :  13 /  13 PASS
  Enterprise Security Audit (security_audit)       :  14 /  14 PASS
  Failure Injection & Chaos (failure_injection)    :   6 /   6 PASS
  Neuronix Core Engine CLI (test_neuronix_core)    :  14 /  14 PASS
  Mutation Resilience Suite (mutation_resilience)  :   6 /   6 KILLED
  Historical Regression Corpus (regression_corpus) :   7 /   7 PASS
  Reproducibility Gate (test_reproducible_iso)     :   6 /   6 PASS
  Performance Benchmarks (test_benchmarks)         :   4 /   4 PASS
  Semantic Closure & Subsystems (semantic_closure) :  35 /  35 PASS
  Conductor Runtime & Socket Activation (runtime)  :  10 /  10 PASS
  Conductor MCP 2026-07-28 Adapter (conductor_mcp) :   8 /   8 PASS
  Conductor Control Protocol v1 (control_protocol) :   6 /   6 PASS
  Vital Observation Contract & Domains (vital_obs) :   4 /   4 PASS
  Vital 16 Collectors & Skills Broker (vital_skl)  :   9 /   9 PASS
  Universal Skill Registry & Delegation (skills)   :   5 /   5 PASS
  RFC 8032 Ed25519 Vectors (crypto_vectors)        :   9 /   9 PASS
  Property-Based Invariants (property_invariants)  :   5 /   5 PASS
  Hardware Contracts (hardware_contracts)          :   7 /   7 PASS
  Mutation Evaluation Gate (mutation_evaluation)   :  10 /  10 KILLED
  Total Executed Assertions                        : 1,384 Assertions
  Failed Verification                              : 0 Failures
  Execution Duration                               : ~195 seconds
  Confidence Score                                 : 100%
═══════════════════════════════════════════════════════════════════
  ✔ NEURONIX VALIDATION SUITE PASSED: 100% OF DECLARED ASSERTIONS VERIFIED
  ✔ NEURONIX RELEASE GATE PASSED: CONTRACT AND RUNTIME LIFECYCLE VERIFIED

Industrial Qualification Evidence: Formal qualification report and empirical test logs are documented in docs/releases/v1.0.5-qualification-report.md. Rather than claiming unbounded mathematical safety proofs, NEURONIX verifies explicit contract assertions and behavioral state machines within defined test scopes:

  • L0 (Static Contracts): AST syntax parsing, declarative markdown specifications, and lint invariants.
  • L1 (Deterministic Unit): Isolated argument validation, property-based fuzzing, and variable sanitization.
  • L2 (System State Machines): Concurrency locking, journal recovery, service daemons, and micro-VM simulation.
  • L3 (Bit-Identical Reproducibility): Single source of truth correlation, two-build derivation equality, and multi-arch matrices.
  • L4 (Hybrid Engine Contracts): Hermetic Calamares installer generation, direct formatting, and atomic rollback state progression without physical ISO dependency.
  • L5 (Real Hypervisor E2E): Full hardware-accelerated QEMU/KVM OS installation, sparse target partitioning, and target disk multi-boot qualification when physical virtualization resources (RW KVM, >=4GB RAM, >=15GB storage) are verified. Deferrals in constrained environments are truthfully recorded as L4 contracts without simulation faking.

Verification Battery Execution:

# Run master industrial test harness (899 tests across 32 suites)
bash tests/run_all_tests.sh

# Run distribution standalone suite (209 tests across 19 suites)
bash tests/test_distro_suite.sh

# Run single source of truth verification (13 tests)
bash tests/test_source_of_truth.sh

# Run multi-architecture evaluation matrix (13 tests)
bash tests/test_multiarch_matrix.sh

# Run two-build functional reproducibility (8 tests)
bash tests/test_two_build_reproducibility.sh

# Run hybrid E2E ISO installation engine gate (8 contract states / 19 real KVM hardware states)
bash tests/e2e/test_iso_install.sh

# Run real OS installation and multi-boot qualification gate (10 tests)
bash tests/e2e/real/test_real_os_install_boot.sh

# Run release lifecycle and target layout gate (34 tests)
bash tests/test_release_lifecycle.sh

# Run multi-hop rollback correctness (13 tests)
bash tests/test_rollback_correctness.sh

# Run enterprise security audit (14 tests)
bash tests/test_security_audit.sh

# Run neuronix-core binary CLI and telemetry invariants (14 tests)
bash tests/test_neuronix_core.sh

# Run fault injection and mutation resilience (6 mutants)
bash tests/test_mutation_resilience.sh

# Run historical regression corpus (REG-001 to REG-007)
bash tests/test_regression_corpus.sh

# Run reproducible checksum database and signature gate (6 tests)
bash tests/test_reproducible_iso.sh

# Run performance benchmarks and latency budgets (4 benchmarks)
bash tests/test_benchmarks.sh

# Run independent conformance corpus (RFC 8785, StateRoot, HDS, Receipts, Transitions)
bash tests/test_conformance_corpus.sh

# Run cross-language differential fuzzing (Python JCS vs Node.js ECMAScript vs Rust)
python3 tests/test_differential_fuzz.py 300

# Run negative reproducibility and mutation sensitivity gate (6 mutants)
bash tests/test_negative_reproducibility.sh

# Compile authoritative evidence snapshot & generate Verification Passport
python3 tools/compile_evidence.py
python3 tools/generate_verification_passport.py
python3 tools/verify_passport.py dist/verification-passport.json

Independent Conformance Corpus & Differential Fuzzing

To ensure that cryptographic StateRoots and Domain Proofs are mathematically portable across runtimes and operating systems, NEURONIX OS maintains an independent conformance corpus and continuous differential fuzzing battery:

  • RFC 8785 Canonical JSON (JCS): Tested against the 20 independent RFC 8785 test vectors covering ECMAScript 5.1 number serialization, IEEE 754 floating point extremes, and lexicographical UTF-16 code unit ordering.
  • StateRoot Mathematical Commitments: Validated across Python and Rust daemon implementations to guarantee bit-exact parity across all five Merkle leaves (L_posture, L_substrate, L_policy, L_evidence, L_provenance).
  • Differential Fuzzing Engine: Executes hundreds of randomized structural fuzzing iterations comparing the Python canonical encoder against the native Node.js V8 engine and the Rust daemon with zero tolerated divergence.

Negative Reproducibility & Sensitivity Testing

Rather than only verifying happy-path executions, NEURONIX OS subjects its assurance architecture to active mutation and falsifiability testing across six critical failure gates:

  1. Policy Mutation: Alterations to security policy contracts immediately produce diverging hashes and fail closed.
  2. Evidence Mutation: Injected defects into verified assertions strictly alter canonical evidence leaves.
  3. Passport Tamper Detection: Forged passport signatures or altered digests trigger immediate cryptographic rejection.
  4. Workload Input Mutation: Distinct workload inputs produce distinct execution receipts and proof roots.
  5. Replay Defense: Missing nonces or replayed domain receipts fail closed.
  6. Causal Transition Integrity: Broken parent state roots in transition proofs abort state progression.

Operational Runbooks (Day-2 Operations)

Production operations and maintenance procedures are documented in docs/operations/:

Architecture Decision Records (ADRs) & RFCs

Formal design choices, invariants, and open governance specifications:

  • ADR-001: Pure Nix Flakes as the Primary Interface
  • ADR-002: Declarative Flake Generation within Calamares
  • ADR-003: Dual-Layer Software Architecture (Immutable Nix Core vs Sandboxed Flatpak)
  • ADR-004: Upstream Synchronization and Fork Mitigation Strategy
  • ADR-005: Hybrid Hardware Detection and Battery Longevity Architecture
  • ADR-006: Structured Btrfs Subvolume Topology and Storage Maintenance
  • ADR-007: OpenCode AI Copilot Daemon and Model Context Protocol Integration
  • ADR-008: Declarative Multi-Tier Kernel Selection and Hardware Hardening Matrix
  • ADR-009: Continuous Industrial Assurance Taxonomy and Truth Policy
  • ADR-009B: Next-Generation Ephemeral Container and Autonomous Hypervisor Architecture
  • ADR-010: Provable State Engine & Causal Lineage Architecture
  • ADR-011: Hyperion Provable Adaptive Execution Architecture (PAEA)
  • NIP-0001: The North Star Thesis and Neuronix Improvement Proposal (RFC) Governance Standard
  • NIP-0002: Provable State Engine & 5-Leaf StateRoot Cryptographic Commitment
  • NIP-0003: Hyperion Adaptive Execution Architecture & Domain Proof Specification

License

NEURONIX OS is open-source software licensed under the Apache License, Version 2.0. See the LICENSE file for complete details.

Copyright (c) 2026 NEURONIX Contributors.