Omarchy AArch64 Image for RiftVM

This project builds and publishes a sparse AArch64 Omarchy disk image exclusively for RiftVM and Apple's Virtualization.framework. It does not publish a general-purpose disk image or a bundle for another virtual-machine frontend.

The image runs natively on Apple silicon: the guest CPU architecture is ARM64, so RiftVM virtualizes it without cross-architecture CPU emulation.

Release pipeline

This repository is one part of a three-repository AArch64 release pipeline:

• riverscn/omarchy-aarch64 maintains the AArch64 runtime adaptation of Omarchy.
• riverscn/omarchy-pkgs-aarch64 builds and publishes the signed stable AArch64 pacman repository.
• This repository assembles the RiftVM disk image from Arch Linux ARM and that signed repository.

The builder downloads the latest package Release manifest and public key on every build. It rejects the snapshot unless:

• the manifest uses the expected stable AArch64 schema;
• its signing fingerprint matches the fingerprint pinned in sources.env;
• every selected package is present;
• the published omarchy package matches the pinned source commit; and
• pacman verifies the signed database and packages.

The installed image keeps the signed repository enabled, so Arch Linux ARM and Omarchy update together:

sudo pacman -Syu

Image contents

The RiftVM image contains:

• Arch Linux ARM's generic AArch64 root filesystem and kernel;
• a 1 GiB EFI System Partition and Btrfs root with @, @home, @log, and @pkg subvolumes;
• Limine, an AArch64 UKI, branded boot menu, factory snapshot, and recovery entries;
• VirtIO graphics, block storage, networking, entropy, input, and audio devices supported by Virtualization.framework;
• PipeWire audio and its PulseAudio, ALSA, JACK, and GStreamer compatibility layers;
• an interactive first-boot wizard for owner credentials, keyboard, Git identity, hostname, and timezone;
• an idempotent service that expands the root partition and Btrfs filesystem when the virtual disk grows; and
• a built-in Omarchy thumbnail for the RiftVM library.

The profile intentionally excludes host-specific physical hardware services and guest components that are unavailable through RiftVM.

The distributed image is intentionally unencrypted. A reusable image cannot safely contain a shared disk-encryption key; per-machine encryption requires a future installer that creates a unique container during import.

One-command installation

Requirements:

• Apple silicon Mac;
• macOS 26 or newer;
• Homebrew; and
• at least 15 GiB available on the destination volume.

The recommended command installs or updates RiftVM, verifies the published Omarchy installer, downloads and verifies every image part, and imports a new machine:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/everettjf/riftvm/main/scripts/install-omarchy.sh)"

If RiftVM 1.0.0 or newer is already installed, the image-only installer is:

/bin/bash -o pipefail -c 'curl -fsSL https://github.com/everettjf/omarchy-aarch64-image/releases/latest/download/install-Omarchy-riftvm.command | /bin/bash'

The installer treats riftvm-release-manifest.json as its sole metadata source. It verifies:

• every numbered part's byte length and SHA-256;
• the complete compressed stream SHA-256;
• the decoded raw disk's virtual size and SHA-256;
• the thumbnail's byte length and SHA-256; and
• the minimum supported RiftVM version.

The portable sparse stream records only allocated extents and recreates them at their exact disk offsets on macOS. The logical disk is 64 GiB while physical host usage stays close to the guest's used data. RiftVM creates fresh machine, NVRAM, and host configuration identities during import.

Release assets

Each Release contains only the RiftVM installation path:

• install-Omarchy-riftvm.command;
• riftvm-release-manifest.json;
• numbered Omarchy-riftvm.sparse.gz.part-* files;
• Omarchy-thumbnail.png;
• SHA256SUMS;
• image provenance; and
• exact package inventories.

GitHub limits each asset to 2 GiB, so the encoded sparse stream is compressed and split into parts of at most 1,900 MiB. The workflow validates local checksums, uploads a draft Release, verifies GitHub's digest for every asset, and publishes only after all checks succeed.

Build

Image assembly executes AArch64 target commands in a chroot and requires a native AArch64 Arch Linux ARM host. Docker, Git, and the standard image tools are required.

Build the image:

./bin/build-image-container

Useful options:

./bin/build-image-container --size 80G --force
./bin/build-image-container --refresh --force
./bin/build-image-container \
  --omarchy-source ../omarchy-aarch64 \
  --omarchy-repository ../omarchy-pkgs-aarch64/pkgs.omarchy.org/stable/aarch64 \
  --force

The default output is:

build/omarchy-aarch64-riftvm.raw
build/omarchy-aarch64-riftvm.raw.sha256

A successful build also emits package inventories and build/image-provenance.txt, including the pinned RiftVM Guest Agent source revision and the digest of the exact binary installed into the image.

Package a local RiftVM Release layout:

./bin/package-riftvm-release \
  --tag v4.0.1-riftvm.1 \
  --output build/release-assets

Tests

Run the static contract and release-packager suite with the adapted Omarchy source as a sibling checkout:

OMARCHY_TEST_SOURCE=../omarchy-aarch64 ./tests/run

The suite verifies script syntax, package boundaries, signed repository provenance, boot configuration, sparse output invariants, RiftVM manifest and installer behavior, split-part checksums, workflow constraints, and the absence of removed runtime integrations.

A complete release additionally requires a native AArch64 image build, checksum verification, RiftVM import, boot, first-run provisioning, shutdown, restart, and forced-stop recovery testing.

See docs/RELEASE_VALIDATION.md for the complete publish, public-download, recovery, and end-to-end acceptance procedure.

License

MIT. See LICENSE.