🖥️ RegicideOSArch

Arch Linux spin of RegicideOS · COSMIC Desktop · AI-Native experiments

Converge and conquer — on Arch.

⚠️ Development Status: The Dagger build pipeline produces a bootable Arch-based rootfs, SquashFS live image, and QCOW2 VM image. COSMIC boots to a greeter, the regicide user can log in, and core apps (podman, distrobox, Rio, NVIDIA open drivers) are pre-installed. The ARM64 build is tested on NVIDIA Spark. This is a side project of the main RegicideOS effort and is not the primary distribution.

Latest release: RegicideOS v0.0.1 — includes a prebuilt regicide-arch.iso live ISO, released in split chunks with SHA256 checksums because GitHub caps individual assets at 2 GiB.

🎯 What is RegicideOSArch?

RegicideOSArch is an Arch Linux-based experimental variant of RegicideOS. It shares the same design goals — immutable Btrfs root, COSMIC desktop, container-first tooling, and AI-native system integration — but uses Arch Linux and pacman instead of Gentoo/Portage. The primary reason is that Arch provides official COSMIC packages in the extra repository and a clean pacman-based install model, making the build pipeline simpler and faster inside nested containers.

Default install size: the current image ships 536 packages (binary, no compiler toolchain) — the Gentoo variant ships 905 (source-built, full toolchain included).

This is a side project. The main RegicideOS distribution remains the Gentoo-based effort in the RegicideOS repository.

🏗️ Architecture

Target note: The current package set is optimized for the bootable QCOW2 VM image. A future ISO/bare-metal profile will diverge where needed. You can make this ISO-friendly by removing the following packages from the default install: qemu-guest-agent, spice-vdagentd, and the full linux-firmware bundle (replace it with targeted linux-firmware-* split packages such as linux-firmware-iwlwifi, linux-firmware-rtw88, amd-ucode, and intel-ucode).

Component	Technology	Purpose	Status
Base distro	Arch Linux	Rolling binary distribution	✅ Working
Init System	systemd	Service management	✅ Working
Filesystem	Btrfs (read-only root + overlays)	Immutable system image with writable layers	✅ Working
Initramfs	mkinitcpio	Btrfs, LUKS, systemd hooks	✅ Working
Bootloader	systemd-boot (unencrypted) / GRUB (encrypted)	UEFI boot	✅ Working
Desktop	COSMIC (official `extra` group)	Wayland-native GPU desktop	✅ Working
Container Runtime	podman + distrobox	Rootless containers and distro compatibility	✅ Working
GPU	NVIDIA open-source driver (`nvidia-open-dkms`)	Proprietary-free NVIDIA stack; optional via `--no-nvidia`	✅ Optional
Terminal	Rio (Flatpak)	GPU-accelerated terminal	✅ Working
Packages	`build-system/packages/*.txt`	Shared package lists for VM/container variants	✅ Added

Directory Layout

build-system/
├── arch/
│   ├── build-qemu-image.sh            # Encrypted LUKS + Btrfs + GRUB builder
│   ├── build-qemu-image-guestfish.sh  # Unencrypted systemd-boot builder (default)
│   ├── build-qemu-image-guestmount.sh # FUSE/guestmount GRUB builder
│   ├── post-install.sh                # Services, initramfs, users, flatpak
│   └── output/                        # Generated images and runner scripts
├── packages/                          # Shared package lists (VM, future ISO)
│   └── vm.txt                         # Default VM package set
├── dagger_pipeline.py                 # Dagger orchestration
└── README.md                          # Build-system reference

📥 Installation / Build

Note: The pipeline produces a compressed rootfs tarball, a SquashFS live image, a bootable QCOW2 VM image, and — with --iso — a bootable live ISO (build-system/arch/output/regicide-arch.iso). A prebuilt live ISO is also available in v0.0.1.

Requirements

64-bit x86 processor
12GB disk space minimum (20GB recommended)
UEFI firmware (or OVMF for VMs)
Internet connection
Docker or Podman for Dagger

Note: the Dagger engine image needs to create the dagger0 bridge, so it cannot run under rootless Podman. If your default docker endpoint is a rootless Podman socket, start the rootful Podman socket and point Dagger at it:
sudo systemctl enable --now podman.socket
DOCKER_HOST=unix:///run/podman/podman.sock sudo -E dagger run python build-system/dagger_pipeline.py --plain

Build from Source

1. Install Dagger

curl -fsSL https://dl.dagger.io/dagger/install.sh | bash

2. Build the unencrypted QCOW2 VM image

cd /path/to/RegicideOSArch
DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --qcow2

Outputs:

build-system/arch/output/regicide-arch.tar.xz — compressed rootfs
build-system/arch/output/regicide-arch.img — live SquashFS image
build-system/arch/output/regicide-arch.qcow2 — bootable VM disk

Note: regicide-arch.img is not a bootable USB image; it is the live SquashFS payload (the ROOTS filesystem). The bootable USB/VM image is the ISO, built with --iso.

3. Try the prebuilt live ISO

Download the split ISO chunks from the v0.0.1 release, reassemble, and verify:

cat regicide-arch.iso.part* > regicide-arch.iso
sha256sum -c regicide-arch.iso.sha256

The ISO boots under UEFI in QEMU/virt-manager or can be written to a USB drive to boot on bare metal. Identify the USB device (/dev/sdX), unmount any partitions on it, and write the ISO:

sudo umount /dev/sdX*
sudo dd if=regicide-arch.iso of=/dev/sdX bs=4M status=progress conv=fsync

Regenerate the live ISO from an existing build:

If you already have a tarball and SquashFS and want a matching bootable ISO without a full rebuild, reuse them:

DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --plain \
  --iso \
  --from-tarball build-system/arch/output/regicide-arch.tar.xz \
  --from-squashfs build-system/arch/output/regicide-arch.img

4. Boot the image

sudo ./build-system/arch/output/run-qemu.sh

Or manually:

cp /usr/share/OVMF/OVMF_VARS.fd /tmp/ovmf-vars.fd
qemu-system-x86_64 \
    -enable-kvm -m 8G -smp 4 -cpu host -machine type=q35,accel=kvm \
    -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
    -drive if=pflash,format=raw,file=/tmp/ovmf-vars.fd \
    -drive file=build-system/arch/output/regicide-arch.qcow2,format=qcow2,if=virtio \
    -netdev user,id=net0,hostfwd=tcp::2222-:22 \
    -device virtio-net-pci,netdev=net0 \
    -vga qxl -vnc localhost:1 \
    -serial file:/tmp/regicide-serial.log \
    -monitor unix:/tmp/regicide-monitor.sock,server,nowait \
    -daemonize

Connect via noVNC:

python -m websockify --web /usr/share/novnc 6081 localhost:5901

Then open http://localhost:6081/vnc.html?host=localhost&port=6081&autoconnect=true.

Default credentials: regicide / regicide. Root password is also regicide; change it immediately on first boot.

5. Boot the live ISO with VNC

You can boot the live ISO headlessly and attach a VNC viewer to watch the COSMIC greeter come up:

cp /usr/share/OVMF/OVMF_VARS.fd /tmp/regicide-iso-vars.fd
chmod u+w /tmp/regicide-iso-vars.fd
qemu-img create -f qcow2 /tmp/regicide-iso-test.qcow2 30G
qemu-system-x86_64 -enable-kvm -m 8G -smp 4 -cpu host \
    -machine type=q35,accel=kvm \
    -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
    -drive if=pflash,format=raw,file=/tmp/regicide-iso-vars.fd \
    -cdrom build-system/arch/output/regicide-arch.iso \
    -drive file=/tmp/regicide-iso-test.qcow2,format=qcow2,if=virtio \
    -netdev user,id=net0,hostfwd=tcp::2225-:22 \
    -device virtio-net-pci,netdev=net0 \
    -vga std -vnc :0

Then connect any VNC client to localhost:5900 and log in as regicide / regicide over forwarded SSH on port 2225.

6. Build options

Flag	Purpose
`--no-nvidia`	Skip the NVIDIA open-source driver stack (useful for CPU-only VMs or ISO prep).
`--no-defer-flatpaks`	Install all Flatpak apps during the image build instead of on first boot.
`--qcow2-size SIZE`	Set the output disk size, e.g. `30G` (default: `20G`).
`--qcow2-output PATH`	Set a custom output path for the QCOW2 image.
`--iso`	Also build a bootable live ISO (`build-system/arch/output/regicide-arch.iso`).
`--from-tarball PATH`	Reuse an existing tarball instead of rebuilding it in Dagger.
`--from-squashfs PATH`	Reuse an existing SquashFS image instead of rebuilding it in Dagger.

Examples:

# Slim CPU-only VM image with no NVIDIA drivers and all Flatpaks pre-installed
DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --qcow2 --no-nvidia --no-defer-flatpaks

# Encrypted build (uses GRUB + LUKS2; prompts for a passphrase)
DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --encrypt

7. Image builder environment variables

The QCOW2 builders read optional environment variables to size partitions. Defaults preserve the original layout.

Variable	Default	Notes
`REGICIDE_DISK_SIZE`	`20G`	Total raw disk size before QCOW2 conversion.
`REGICIDE_EFI_SIZE`	`512M`	EFI system partition.
`REGICIDE_ROOTS_SIZE`	`14G` (`12G` for encrypted builds)	Btrfs root partition. Increase if pre-installing many packages.
`REGICIDE_OVERLAY_SIZE`	`4G`	Overlay upperdir partition for writable `/etc`, `/var`, `/usr`.

Example:

REGICIDE_ROOTS_SIZE=20G REGICIDE_OVERLAY_SIZE=8G \
  DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --qcow2

🪟 WSL Build

A separate Dagger pipeline builds a WSL2-ready rootfs tarball.

Build the WSL rootfs

DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline_wsl.py --plain

Output:

build-system/arch/output/regicide-arch-wsl.tar.gz — gzip-compressed rootfs for wsl --import

Import into WSL

From Windows PowerShell or CMD:

wsl --import RegicideOSArch C:\WSL\RegicideOSArch \
  \\wsl$\<distro>\home\<user>\code\personal\RegicideOSArch\build-system\arch\output\regicide-arch-wsl.tar.gz \
  --version 2

Then start it:

wsl -d RegicideOSArch

Default credentials: regicide / regicide. wsl.conf sets regicide as the default user and enables systemd.

🔄 System Maintenance & Updates

RegicideOSArch ships with a small update/rollback toolkit installed in the image. These tools operate on the Btrfs /overlay subvolumes (etc, var, usr) and snapshot them under /roots/.regicide-snapshots. All commands require root privileges.

Package management

Use regicide-update instead of running pacman directly so every transaction is snapshotted and can be rolled back:

# Sync package databases
sudo regicide-update sync

# Upgrade all installed packages
sudo regicide-update upgrade

# Install or remove packages
sudo regicide-update install rio firefox
sudo regicide-update remove firefox

If a transaction fails, regicide-update automatically schedules a revert to the pre-transaction snapshot; reboot to roll back.

Snapshot rollback

# List available snapshot sets
sudo regicide-rollback list

# Revert to a snapshot at the next boot
sudo regicide-rollback revert 2026-07-08_12:00:00_pre_upgrade

# Cancel a pending revert
sudo regicide-rollback revert --cancel

The regicide-rollback-apply.service applies the chosen snapshot before /etc, /var, and /usr are mounted.

Rootfs update

To replace the base rootfs with a newer release tarball:

# Download a release image
sudo regicide-image fetch https://example.com/regicide-arch.tar.xz \
  --checksum-url https://example.com/regicide-arch.tar.xz.sha256

# Install it into /roots
sudo regicide-image install /var/cache/regicide-image/regicide-arch.tar.xz

This extracts the tarball into /roots and reseeds the overlay subvolumes so the next boot uses the new base system while preserving user data on the HOME partition.

🤖 AI-Agent Build Procedure

Deterministic steps an AI agent can follow. All paths assume the repo was cloned into the current working directory.

A. Build the QCOW2 image

Run the Dagger pipeline.

cd "$(pwd)"
DAGGER_PROGRESS=plain dagger run python build-system/dagger_pipeline.py --qcow2

Verify the tarball exists.

test -f "$(pwd)/build-system/arch/output/regicide-arch.tar.xz"

Verify the SquashFS image exists and is non-empty.

test -s "$(pwd)/build-system/arch/output/regicide-arch.img"

Verify the QCOW2 image exists.

test -s "$(pwd)/build-system/arch/output/regicide-arch.qcow2"

Success criterion: all commands return exit code 0 and the QCOW2 file has a partition table.

sudo parted -s "$(pwd)/build-system/arch/output/regicide-arch.qcow2" print > /dev/null 2>&1

B. Boot the generated QCOW2

Ensure no other QEMU process is holding the image.

pkill -9 -f 'qemu-system-x86_64.*regicide-arch' 2>/dev/null || true

Start the VM with the generated runner script.
```
sudo ./build-system/arch/output/run-qemu.sh
```
Success criterion: the VM reaches the COSMIC greeter. Log in as regicide / regicide and run:
```
systemctl status systemd-logind
```
It should report active (running).

🗺️ Roadmap

🤝 Contributing

This is a side project; primary development focus remains on RegicideOS. Contributions here are welcome for Arch-specific improvements, faster CI builds, and COSMIC packaging experiments.

Found a bug? File an issue in this repository with the command you ran, full logs, and your environment.

📜 License

RegicideOSArch is licensed under the GNU General Public License v3.0.

Built on the foundation of Arch Linux and the COSMIC Desktop ecosystem.

Name		Name	Last commit message	Last commit date
build-system		build-system
data		data
docs		docs
src/regicide_update		src/regicide_update
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

🖥️ RegicideOSArch

Arch Linux spin of RegicideOS · COSMIC Desktop · AI-Native experiments

🎯 What is RegicideOSArch?

🏗️ Architecture

Directory Layout

📥 Installation / Build

Requirements

Build from Source

1. Install Dagger

2. Build the unencrypted QCOW2 VM image

3. Try the prebuilt live ISO

4. Boot the image

5. Boot the live ISO with VNC

6. Build options

7. Image builder environment variables

🪟 WSL Build

Build the WSL rootfs

Import into WSL

🔄 System Maintenance & Updates

Package management

Snapshot rollback

Rootfs update

🤖 AI-Agent Build Procedure

A. Build the QCOW2 image

B. Boot the generated QCOW2

🗺️ Roadmap

🤝 Contributing

📜 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🖥️ RegicideOSArch

Arch Linux spin of RegicideOS · COSMIC Desktop · AI-Native experiments

🎯 What is RegicideOSArch?

🏗️ Architecture

Directory Layout

📥 Installation / Build

Requirements

Build from Source

1. Install Dagger

2. Build the unencrypted QCOW2 VM image

3. Try the prebuilt live ISO

4. Boot the image

5. Boot the live ISO with VNC

6. Build options

7. Image builder environment variables

🪟 WSL Build

Build the WSL rootfs

Import into WSL

🔄 System Maintenance & Updates

Package management

Snapshot rollback

Rootfs update

🤖 AI-Agent Build Procedure

A. Build the QCOW2 image

B. Boot the generated QCOW2

🗺️ Roadmap

🤝 Contributing

📜 License

About

Topics

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages