Skip to content

nucleus

Enterprise-grade, hardened, hardware-accelerated Linux kernel compilation and packaging factory for cordanaLLM/imago and high-performance bare-metal clusters.

1. Mission & Ecosystem Architecture

cordanaLLM/nucleus is the dedicated kernel compilation sister repository to cordanaLLM/imago.

In traditional cloud image builds, compiling custom Linux kernels directly inside Packer or Image Builder virtual machines introduces severe bottlenecks: multi-hour build cycles, CPU resource exhaustion, duplicate compilation across matrix variants, and brittle compiler toolchain setup. cordanaLLM/nucleus solves this by decoupling kernel compilation into a dedicated, hermetic build pipeline.

The repository compiles, patches, hardens, and packages four production kernel streams across x86_64 (AMD64), arm64 (aarch64), and riscv64 architectures. The output artifacts—native Debian packages (.deb) and systemd Unified Kernel Images (.efi, unsigned until Secure Boot signing is wired)—are built from one manifest. The Debian packages are published as GitHub Release assets with a keyless cosign signature over their checksum file and consumed downstream by cordanaLLM/imago; no APT archive exists and no Unified Kernel Image is published yet (Packaging, section 5).

sequenceDiagram
    autonumber
    participant KF as nucleus (Sister Repo)
    participant GH as GitHub Releases
    participant OCI as GitHub Container Registry (ghcr.io)
    participant CI as imago (Image Forge)
    participant BM as Bare-Metal & Hypervisor Fleet

    Note over KF: Upstream kernel.org source fetched & verified
    KF->>KF: make bindeb-pkg (linux-image, linux-headers, linux-libc-dev)
    KF->>KF: systemd-ukify (Kernel + cmdline + optional initrd -> unsigned UKI .efi)
    KF->>GH: Publish .deb packages, SHA256SUMS & cosign bundle
    KF->>OCI: Push Unified Kernel Images (UKI) as OCI artifacts (planned; unsigned today)
    KF->>CI: repository_dispatch (kernel_release_published)
    CI->>CI: Renovate / sync workflow updates versions.json
    CI->>GH: Download pre-compiled .deb packages during Packer build
    CI->>BM: Deploy golden cloud image with hardened kernel
    OCI->>BM: Direct netboot / systemd-boot UKI streaming

2. Live Kernel Release Streams

All versions, upstream source tarball URLs, and release tags are managed exclusively through versions.json.

Stream Linux Version Status Primary Target Workloads Hardware Acceleration Key Features
bleeding 7.3-rc7 Mainline Next-gen AI clusters, high-frequency eBPF NVIDIA Blackwell B200 / RTX 5090 (open kernel modules checked in CI, packaging 5.7), CXL 3.0 sched-ext dynamic scheduler, PCIe 6.0, cutting-edge DRMs
mainstream 7.2.11 Stable Production container hosts, virtualization Intel Arc Battlemage Xe2 (xe) and AMD Radeon for ROCm (amdgpu with KFD) are built and claimed across all four streams on x86_64 (arm64 waits for a consumer requirement document) BBR congestion control, mq-deadline (Level Zero is user space on the xe uAPI)
lts 6.18.58 Longterm Enterprise Kubernetes nodes, OpenZFS storage Intel Arc Alchemist (i915, not on realtime); NVIDIA's driver is out of tree Rock-solid stability, OpenZFS module build checked against each release (packaging 5.6), strict overcommit
realtime 7.2.11 PREEMPT_RT Low-jitter game servers, edge gateways Low-latency audio & SDR hardware Full preemptible kernel (PREEMPT_RT), 1000Hz timer, threaded IRQs

3. Core Architectural Pillars

  • Single Source of Truth (SSOT): Kernel versions, upstream archives, patch queues, and architecture targets are strictly declared in versions.json and validated by JSON Schema.
  • NASA / JPL Power of 10 Compliance: All automation and build scripts enforce set -euo pipefail, short functions ($\le 60$ lines), localized variables, bounded control loops, and zero ShellCheck warnings.
  • Modular KConfig Architecture: Kernel configurations are partitioned into composable fragments (the security baseline, one per architecture, the Kubernetes node fragment kconfig/k8s-node.config, and kconfig/streams/<stream>.config), merged deterministically by scripts/merge-config.sh.
  • Zero-Leak Invariant: Codebase is protected against private network leaks (zero RFC 1918 addresses) and local workstation paths (zero /home/... or /Users/... references).
  • Dual Packaging Engine: Standard Debian packages (.deb) for apt-based distributions and systemd Unified Kernel Images (.efi, unsigned until Secure Boot signing is wired) for bare-metal streaming.

4. Quickstart Recipes

To verify and install a published kernel release, see Verify and Install a Release.

Inspecting Configured Streams

Validate the declarative manifest and list available build channels:

make lint
python3 -c "import json; data=json.load(open('versions.json')); print(json.dumps(data['streams'], indent=2))"

Dry-Run Kernel Build Pipeline

State the fetch, the configuration resolution, the make command and the expected kernel release; nothing is written. DRY_RUN defaults to true in the Makefile:

make build-kernel STREAM=mainstream ARCH=x86_64 DRY_RUN=true

Or directly via the build script:

./scripts/build_kernel.sh --stream=mainstream --arch=x86_64 --dry-run

Building Full Debian Kernel Packages

Compile with GCC on all available host cores (--jobs defaults to nproc):

make build-kernel STREAM=mainstream ARCH=x86_64 DRY_RUN=false

Or directly via the build script:

./scripts/build_kernel.sh --stream=mainstream --arch=x86_64

Compiled Debian packages will be placed into output/<stream>-<arch>/:

  • linux-image-<kernelrelease>_<debian_version>-lusoris<N>_<debian_arch>.deb
  • linux-headers-<kernelrelease>_<debian_version>-lusoris<N>_<debian_arch>.deb
  • linux-libc-dev_<debian_version>-lusoris<N>_<debian_arch>.deb

A cross build ships no headers package (Packaging).

Synthesizing Unified Kernel Images (UKI)

Wrap a built kernel into a single EFI binary with ukify: the systemd-stub plus the kernel, its command line, os-release, kernel release and SBAT metadata. An initramfs is embedded only when --initrd is given. The image is not Secure Boot signed, and no CPU microcode is embedded.

./scripts/package-uki.sh --stream=mainstream --arch=x86_64 --vmlinuz=<path> [--initrd=<path>]

Without --dry-run this requires a built kernel image and ukify (systemd-ukify, plus systemd-boot-efi for the stub), and refuses if either is missing rather than emitting something named like a UKI. scripts/check_uki.py then checks what ukify wrote, and package-uki.sh deletes it before any checksum unless it is a PE image with the UKI sections the script wires; see section 3 of Packaging. --dry-run writes a marked text file under output/<stream>-<arch>-dry-run/, never a .efi and never a checksum.

Running Test Gates

Ensure all kconfig fragments, shell scripts, and privacy invariants pass validation:

make test