Pulsar OS ISO

This repository contains the ISO build script, the configuration files for preinstalled packages, and the Github Actions workflows.
PulsarOS is built 100% by Github Actions, fully auditable end-to-end, and the ISO images are uploaded to Sourceforge (since Github Releases has very low size limits).

Prerequisites

The build script checks for missing dependencies and tells you what to install. But if you want to set everything up beforehand:

Arch Linux / CachyOS / Manjaro

sudo pacman -S --needed \
  arch-install-scripts squashfs-tools grub xorriso mtools dosfstools \
  binutils libisoburn sassc imagemagick psmisc \
  fakeroot rsync jq curl unzip wget git \
  meson ninja blueprint-compiler gettext gobject-introspection gtk-update-icon-cache cmake \
  cargo rust

The last two lines are only needed for --local builds, which compile the packages from the /PKG folder (custom Nautilus needs meson/ninja; the Spotlight launcher is a Rust/GTK4 app built with cargo).

Debian / Ubuntu / Pop!_OS

sudo apt-get install -y \
  mmdebstrap squashfs-tools grub-common grub-efi-amd64-bin grub-pc-bin \
  xorriso mtools dosfstools binutils unzip sassc imagemagick psmisc \
  debian-archive-keyring rsync jq curl wget fakeroot git

The rEFInd Secure Boot builds also need the signing tool: sbsigntools on Arch, sbsigntool on Debian/Ubuntu. The build script only requires it when the Pulsar MOK private key is present (ISO/assets/secureboot/pulsar-mok.key, see Secure Boot & MOK).

What each package does

Package	Purpose
arch-install-scripts / mmdebstrap	Bootstrap the base chroot (pacstrap / mmdebstrap)
squashfs-tools	Compress the rootfs into a SquashFS image
grub / grub-common + grub-pc-bin + grub-efi-amd64-bin	Build the GRUB bootloader for the ISO
xorriso	Create hybrid ISO images (BIOS + UEFI)
mtools	Manipulate FAT filesystems (EFI image inside ISO)
dosfstools	Format FAT partitions (EFI image)
binutils / libisoburn	Linker and ISO manipulation tools
sassc	SCSS compiler for GRUB and Plymouth themes
imagemagick	Image processing for branding assets
psmisc	Provides fuser to kill leftover processes on port 5900
fakeroot	Build packages without real root privileges
rsync	Sync the base chroot into the working target
jq / curl / wget / unzip / git	Download and extract resources during build
meson / ninja / blueprint-compiler / gettext / gobject-introspection	Build the custom Nautilus (Finder) from source (--local)
cargo / rust	Build the native Spotlight launcher (Rust/GTK4, no Python) (--local)

For QEMU testing (optional)

If you want to test ISOs without burning real hardware:

# Arch
sudo pacman -S qemu-full edk2-ovmf

# Debian/Ubuntu
sudo apt-get install -y qemu-system-x86 ovmf

Building the ISO

The main file for building single ISOs is build-iso.sh, which accepts the following flags:

• --branch stable, replacing stable with any other Debian branch; currently only stable can be used.
• --local to package from the packages in the /PKG folder, which must be in the same folder that contains the /ISO folder
• --refind Indicates that the rEFInd version should be built
• --grub Builds the GRUB version
• --arch Builds the ARCH version (if this flag is absent, the Debian version is built)
• --nvidia Build ISO image with privative drivers (BROADCOM, NVIDIA, etc...)
• --minimal Minimal lightweight build (~2-3GB target)

Building Multiple ISOs in Parallel

To build multiple ISO editions concurrently with full isolation, thermal balancing, and zero race conditions, use build-parallel.sh. It automatically synchronizes concurrent tasks using flock and creates isolated rootfs targets to prevent directory collisions.

Flags and Usage

Target Flags	Description
--all	Builds all variants (Arch GRUB, Arch rEFInd, Debian GRUB, Debian rEFInd). Default if none specified.
--arch-grub	Builds the Arch Linux edition with GRUB.
--arch-refind	Builds the Arch Linux edition with rEFInd.
--debian-grub	Builds the Debian edition with GRUB.
--debian-refind	Builds the Debian edition with rEFInd.

Filter Flags	Description
--arch / --arch-only	Compiles only Arch Linux editions.
--debian / --debian-only	Compiles only Debian editions.
--grub / --grub-only	Compiles only GRUB editions.
--refind / --refind-only	Compiles only rEFInd editions.

Additional Options	Description
--minimal	Minimal lightweight build (~2-3GB target).
--full	Standard full build.
--clean-base	Deletes and rebuilds the base cache from scratch.
--nvidia	Includes proprietary NVIDIA and Broadcom drivers.
--branch, -b <branch>	Build branch (stable, forky, rolling). Default is stable.
--version, -v <ver>	Version tag for the ISOs.
--skip-pkg	Skips the local package build phase in /PKG.
--production	Uses remote repositories instead of local packages.

Examples

# Build Arch GRUB, Arch rEFInd, Debian GRUB, and Debian rEFInd simultaneously:
sudo ./build-parallel.sh --all

# Build specific combinations:
sudo ./build-parallel.sh --arch-grub --arch-refind --debian-grub

# Build all Arch versions, minimally:
sudo ./build-parallel.sh --arch --minimal

# Build all Debian versions with rEFInd:
sudo ./build-parallel.sh --debian --refind

Testing in Chroot or the ISO quickly

The file for quickly testing the ISOs is run-qemu.sh, which accepts the following arguments:

• --iso Boots from a previously built ISO image instead of directly from the chroot (build/rootfs-target)
• --refind Selects the rEFInd bootloader (used with --iso)
• --grub Selects the GRUB bootloader (used with --iso, default)
• --nvidia Uses the NVIDIA variant of the rootfs/ISO
• --arch Uses the ARCH variant of the rootfs/ISO
• --debian Uses the Debian variant of the rootfs/ISO (default)
• --branch|-b <branch> Sets the branch, must be stable, forky or rolling (default: stable)

Without --iso, the script boots the compiled rootfs (build/rootfs-target-<branch>-<distro>[-nvidia]) directly via 9pfs, without the need to package an ISO, making testing instantaneous.

Building from GH Actions

The ISO version, release name, and branch must be specified.

Secure Boot & MOK

Both ISO bootloaders ship a Secure Boot chain. The signed binaries live in ISO/assets/secureboot/ (shim and MokManager come from Debian and are signed by Microsoft; the Pulsar MOK public key is generated by generate-mok.sh).

GRUB editions (--grub): firmware -> Debian shim (Microsoft-signed) -> Debian-signed GRUB. GRUB loads the kernel with the Linux boot protocol, so the kernel does not need signing and no enrollment is required.

rEFInd editions (--refind): firmware -> bootx64.efi (shim) -> grubx64.efi (rEFInd signed with the Pulsar MOK key). rEFInd loads the live kernels as EFI stub images, so the build also signs vmlinuz and vmlinuz-recovery with the same key.

The rEFInd chain requires a one-time MOK enrollment per machine, because shim only trusts binaries signed by keys the user enrolled:

1. Write the ISO with dd / balenaEtcher (this chain is for direct USB boot; when booting through Ventoy, Ventoy provides its own shim/MOK handling).
2. With Secure Boot active, first boot stops at MokManager. Select Enroll key from disk, locate EFI/BOOT/refind.cer, confirm, and reboot.
3. rEFInd now boots. On the installed system, run sudo pulsar-enroll-mok (ships with pulsaros-refind) to import the MOK with mokutil; MokManager asks to confirm after the reboot.

Notes:

• Building the rEFInd secure-boot ISO requires sbsigntool on the build host (sbsign) and the private key ISO/assets/secureboot/pulsar-mok.key, which is gitignored on purpose. Recreate it with ISO/assets/secureboot/generate-mok.sh.
• Kernels stay in the ISO for the Ventoy/legacy paths untouched; only the EFI-stub copies that rEFInd loads are signed.

Tube OS (Smart TV & Home Server Edition)

Tube OS provides a cinematic 10-foot TV user interface (Openbox + Tube OS UI / Plasma Bigscreen) and background CasaOS/Docker server capabilities.

Building Tube OS ISO

Use tubeos/build-tubeos.sh (or build-tubeos-iso.sh):

# Build Arch Linux edition (Plasma Bigscreen + Tube OS UI + CasaOS) [Fast/Quick Mode]
sudo ./tubeos/build-tubeos.sh --arch --quick

# Build Debian edition (Openbox + Tube OS UI + CasaOS) [Fast/Quick Mode]
sudo ./tubeos/build-tubeos.sh --debian --quick

# Rebuild only modified packages incrementally
sudo ./tubeos/build-tubeos.sh --arch --incremental

Running and Testing with run-tubeos-vm.sh

The run-tubeos-vm.sh script automates QEMU virtual machine creation, UEFI/OVMF firmware configuration, port forwarding, and disk persistence.

How run-tubeos-vm.sh works:

1. Boot from Live ISO (Installation Mode):

   ./run-tubeos-vm.sh --iso --arch
   # or for Debian:
   ./run-tubeos-vm.sh --iso --debian

   • Automatically attaches a virtual disk (build/tubeos-disk.qcow2, 25GB) and boots the ISO with KVM hardware acceleration.
   • Forwards ports to your host machine:
     • Host http://localhost:8088 -> Guest port 80 (Tube OS Web Installer / CasaOS Dashboard)
     • Host http://localhost:8070 -> Guest port 8070 (DockerMigrate)
     • Host localhost:2222 -> Guest port 22 (SSH)

2. Boot from Installed Virtual Disk (Installed Mode): Once installed via the Web Installer at http://localhost:8088, boot directly into your installed system:

   ./run-tubeos-vm.sh --disk

3. Reset Virtual Disk (Fresh Start): Wipes the existing virtual disk and boots a clean ISO:

   ./run-tubeos-vm.sh --reset-disk --iso

4. LAN Bridge & mDNS Mode: Bridges directly to virbr0 for direct network access (http://tubeos.local):

   ./run-tubeos-vm.sh --iso --passthrough

Options Reference for run-tubeos-vm.sh

Option	Description
--iso	Boots from the Live ISO image with the virtual disk attached (default).
--disk	Boots directly from the installed virtual disk (tubeos-disk.qcow2).
--arch	Selects the Arch Linux ISO (tubeos-stable-arch-grub.iso).
--debian	Selects the Debian ISO (tubeos-stable-debian-grub.iso).
--reset-disk	Re-creates an empty virtual disk before booting.
--disk-size <size>	Sets the virtual disk size (default: 25G).
--mem <size>	Sets VM RAM allocation (default: 4G).
--smp <cores>	Sets VM CPU core count (default: 4).
--port <port>	Sets host port for Web UI access (default: 8088).
--passthrough	Enables bridge networking on virbr0 for mDNS LAN access (tubeos.local).
--headless	Runs without graphical window (terminal only).

Packages

PulsarOS is fully declarative; packages are built and obtained from repo PKG

License

All the code is licensed under MIT-INLED