nip/docs/architecture.md

The Architecture of Immutability

NexusOS as an Immutable System

Document Version: 250714_1838
Last Updated: June 14, 2025
Target Audience: System Administrators

---

1. The Core Principle: Immutability as a Compilation Target

The fundamental design philosophy of NexusOS treats immutability not as a feature to be added, but as an inherent property of the system compilation process. Rather than retrofitting atomicity onto an existing mutable system, NexusOS produces immutable systems by design through its build orchestration.

An "Immutable NexusOS" deployment is the artifact produced when the nexus build orchestrator compiles a system definition (system.nexus.nim) with the explicit intent of creating a hermetic, read-only, and cryptographically verifiable system image. This approach eliminates dependency on external tools like rpm-ostree, as the entire stack—from NimPak package management to Generation lifecycle management—is architected around immutability from the ground up.

2. The Pillars of NexusOS Immutability

The immutable system architecture is built upon four foundational pillars:

Pillar 1: The Declarative Single Source of Truth

Every aspect of the system—kernel parameters, installed packages, configuration files, and system policies—is declared in a single, version-controlled system.nexus.nim file. This eliminates hidden state and prevents manual, out-of-band modifications that could compromise system integrity or reproducibility.

Pillar 2: The nexus Compiler as System Orchestrator

The nexus command functions as a system compiler. It parses the declarative system definition and executes a deterministic build process that produces a complete, bootable system image. A critical step in this compilation process is setting the read-only flag for the root filesystem, ensuring that the deployed system cannot be modified at runtime.

Pillar 3: The GoboLinux Architecture for Physical Separation

The root filesystem (/) of an immutable NexusOS deployment consists almost exclusively of symlinks pointing to specific, versioned, read-only directories under /Programs. This architecture provides:

• Version isolation: /usr/bin/nginx → /Programs/Nginx/1.2.3/bin/nginx
• Library pinning: /lib/libssl.so → /Programs/OpenSSL/3.0.1/lib/libssl.so

The base system is a curated collection of read-only symbolic links. Security hardening measures are essential:

• Use of relative symlinks where possible
• Rejection of path traversal attempts
• Optional noexec,nodev mount flags for /Programs
• Symlink ownership and permission validation

Pillar 4: Atomic Updates via Symlink Transactions

System updates never modify files in the running system. The update process follows these steps:

1. Build Phase: The nexus updater constructs the new system Generation in an isolated temporary area, creating new versioned directories under /Programs (e.g., /Programs/Nginx/1.2.4/)
2. Verification Phase: The build is validated for completeness and integrity before deployment
3. Atomic Transaction: A single, atomic operation re-points all root filesystem symlinks to the new program versions
4. Boot Manager Update: NexusBoot is updated to offer the new Generation as a boot option

This process is inherently atomic—either the entire transaction succeeds, or the system remains in its previous state. There are no partial updates.

3. User Interaction Model in Immutable Deployments

In an immutable NexusOS deployment, user freedom is not restricted but rather channeled into designated, safe areas. This enforces operational discipline while maintaining system stability.

Package Installation Behavior

Attempting global installation:

$ nip install htop
Error: System is immutable. To install for your user only, specify a target cell:
  nip install --cell=my-tools htop

The nip client detects write permission restrictions on /Programs and provides clear guidance.

NexusCell Enforcement

The system enforces isolation by requiring users to explicitly declare their intent to install software into their own isolated NexusCell. This ensures:

• The base system remains untouched and guaranteed stable
• User-installed software is isolated and does not affect system-level operations
• Troubleshooting is simplified by clear separation of system and user software

System Modifications via Declarative Overlays

Administrators requiring base system changes do not execute imperative commands. Instead, they:

1. Write a declarative Overlay Fragment specifying the desired changes
2. Submit the fragment to the nexus system for compilation
3. Allow nexus to compile a new, official Generation
4. Deploy the new Generation to the fleet through standard update mechanisms

This workflow ensures all system changes are:

• Version controlled
• Auditable
• Reproducible
• Testable before deployment

4. Declarative System Definition

The following example demonstrates how an immutable system is declared in a Fragment file:

# secure_appliance.fragment.nim

# Define a system artifact named "secure-medical-terminal"
systemArtifact "secure-medical-terminal" do
  version "2025.07.1"
  
  # Immutability configuration
  target do
    osType "immutable"
    rootFs "read-only"
    bootloader "NexusBoot"
    defaultGeneration true
  
  # System composition
  baseStream "nexusos-lts-2025.04"
  installPackages "medical-viewer-app", "secure-browser"
  
  # User policy enforcement
  userPolicy do
    allowNipCells true                    # Users may install software in their cells
    globalPackageInstall "denied"         # System-level 'nip install' is blocked

5. Operational Advantages

NexusOS achieves immutability through architectural design rather than external tooling. This provides several operational benefits:

Compared to Traditional Approaches

• rpm-ostree, Valve SteamOS: Attempt to retrofit immutability onto existing mutable distributions
• NexusOS: Immutability is a compilation target, not a post-processing step

Key Benefits for System Administrators

1. Predictable State: Every deployed system is bit-for-bit reproducible from its declaration
2. Atomic Rollback: Failed updates can be instantly reverted by selecting a previous Generation at boot
3. Fleet Consistency: All systems built from the same declaration are identical
4. Simplified Troubleshooting: Clear separation between system and user modifications
5. Security Hardening: Read-only root filesystem prevents entire classes of attacks
6. Compliance: Immutable systems simplify audit and compliance requirements

---

Conclusion

The ability to deliver atomic, immutable systems is not a feature bolted onto NexusOS—it is the logical consequence of fundamental architectural decisions. By treating system deployment as a compilation process with immutability as a first-class property, NexusOS provides system administrators with unprecedented control, predictability, and operational safety.