1.Introduction to Nucleus

Introduction to Nucleus

Warning

• Nucleus is not designed for that group of linux users that have no experience of OS installation from minimal ISO.
• Basic literacy of VIM and navigating within TTY is expected.

This project was started with the goal of making migrations to NixOS fearless. The idea is to make a NixOS configuration predictable, reproducible,and easy to understand, so that moving from one machine to another or rebuilding an existing machine from scratch does not feel like starting over. Nucleus provides a structured approach for organizing a personal NixOS configuration while keeping the system close to native NixOS concepts and avoiding unnecessary abstraction. The goal is not to hide NixOS behind another framework, but to provide a simple architecture that makes configuration easier to reason about, maintain, and migrate over time.

Nucleus is a lightweight, abstraction-free and easy to debug configuration architecture inspired by the dendritic pattern for maintaining NixOS systems using some of the best practices encouraged by the ecosystem. Nucleus is designed for NixOS users that are overwhelmed by tons of different approaches for configuring your NixOS systems.

Nucleus focuses on keeping configurations modular and understandable by separating reusable components from host-specific configuration.

Note

Why the name Nucleus ? The architecture is named nucleus because its working model is somewhat similar to nucleus in real animal/plant cell. The root flake.nix manages multiple hosts and their capabilities and consider them as an organelle.

Goals

Nucleus aims to provide:

• A predictable structure for personal NixOS configurations.
• Clear separation between shared configuration, reusable features, and host-specific details.
• A reproducible installation and migration workflow.
• A configuration layout that remains understandable over long periods of time.
• A practical starting point for users who want to build and maintain their own NixOS systems using the best NixOS practices.

Scope

Nucleus is designed for personal NixOS configurations.

It can comfortably support configurations with multiple machines, such as:

• personal laptops
• desktops
• home servers
• development machines

Nucleus can technically support many hosts, but it is optimized for personal ownership rather than large-scale fleet management. Ideally, a setup with less than 10 individual hosts should remain straightforward to maintain with this architecture.

The architecture assumes that the person maintaining the configuration understands the design decisions behind it. For larger teams or deployments where many people manage many machines, dedicated infrastructure-oriented frameworks may be more appropriate.

Host Management Model

Nucleus follows a host-oriented configuration model.

The repository can contain multiple hosts, but each host is treated as an individual system with its own requirements and configuration.

When adding a new host:

1. Start from the existing architecture.
2. Adapt features according to the needs of that machine.
3. Move host-specific configuration into the corresponding host directory.
4. Import and maintain the configuration for that host independently.

Nucleus enables you to manage all your personal machines from a single configuration repository, where each machine runs one active host configuration. It is not designed for infrastructure-level fleet management at scale for thousands of machines.

Non-goals

Nucleus is intentionally not designed to:

• Replace general-purpose Nix configuration frameworks.
• Provide fleet management on infrastructure level.
• Solve every possible NixOS configuration scenario which is out of the project scope.
• Become a universal standard for managing NixOS and Systems with Nix Installed.

Nucleus is designed specifically for personal NixOS configurations where simplicity, ownership, and maintainability are the priority.

Tech Stack

The nucleus architecture primarily uses flakes as the main foundation, with the following flakes as core dependencies.

• import-tree: used for recursively importing *.nix files
• home-manager: used for declaratively configuring dotfiles in native nix.
• disko: used to declaratively automate the formatting, partitioning and mounting of the target disk.
• nixpkgs: uses rolling release instance of NixOS for building OS generation and programs included in package list.

Core Concepts

Nucleus organizes configuration into three layers:

Common Configuration

Configuration shared by every machine.

Examples:

• disko layout for partitioning
• core NixOS configuration for both servers and desktops.
• custom overlays and derivations shared across machines.

Configuration Modules as Features

Reusable system capabilities.

Examples:

• desktop environments
• services
• development tools
• applications

Hosts and Per Machine Configuration

Machine-specific configuration.

Examples:

• hardware configuration
• kernel modules
• drivers