4.4 KiB
HydraOS Gentoo image and installer
Approved overall scope: Gentoo, installableISO, first ASUS FX517ZC, full autonomous development including dependency patches. This document fixes the bounded image pipeline; it does not authorize overwriting the laptop disk.
Build and update model
Use amd64 systemd stage3 20261011T170049Z, verified against Gentoo release key 13EBBDBEDE7A12775DFDB1BABB572E0E2D182910. Pin Portage snapshot 4696089e782c20b5f0c04952f6698d6a8cc1acb4 and all custom source/patch versions. Official binpkgs with signature verification are preferred; only packages needing changed flags or testing keywords build from source. Keep compiler concurrency4 and emerge job concurrency1 initially. Preserve Portage database/world/update hooks in installed system. Record resulting package versions and build inputs; do not promise bit-for-bit reproducibility of rolling binhost content.
Build in a dedicated rootless Podman store/container under ignored build state, without host package installs or root access to host disks. Input archives and repository are read-only mounts. Sources/cache/artifacts live under this project. A failed build is resumable; no global image/container prune commands.
System contents
QEMU/KVM, OVMF, labwc>=0.20.0, adapted virt-viewer, Python CLI, foot, greetd, NetworkManager, dnsmasq/nftables, PipeWire/WirePlumber, sudo, distribution kernel, linux-firmware, SOF and Intel microcode. IntelGPU is default; discreteGPU is not assigned to a guest automatically. Generic initramfs covers virtio and ASUS vmd/nvme/xhci/thunderbolt/i915. No preinstalled guestOS or cloud accounts.
Live session permits explicit local administration and network configuration; no default network login service. Installed account is configured by installer, with a password prompt; do not ship a universal installed-system password. The minimal session contains fullscreen guests, recoveryterminal and concise initial guidance when no VM exists. Default host session never shuts down guests. Other desktop packages remain installable normally through Gentoo.
Network
Fresh installed system creates hydrabr0, subnet10.203.0.0/24, host10.203.0.1, DHCP/DNS for guests, forward/NAT Internet access. New profiles use this network; VM↔VM and LAN→VM connections are not port-restricted by HydraOS. LAN router still needs a route to the guest subnet unless the physical uplink is bridged, which is not generally available over Wi-Fi. Detect conflicting existing subnet and fail clearly instead of silently replacing external networkconfiguration. QMP/SPICE remain private Unix sockets. Bridge permission is narrowly granted to the HydraOS VM user; no blanket sudo command runner.
Boot medium
UEFI x86_64, SecureBoot disabled initially; GRUB -> distribution kernel -> dracut with dmsquash-live -> squashfs root plus volatile OverlayFS. Label HYDRA_OS, cmdline root=live:CDLABEL=HYDRA_OS rd.live.image rd.live.overlay.overlayfs=1 ro. Do not copy entire live image into RAM. Runtime changes in live session are explicitly nonpersistent; persistent VM disks belong on installed storage.
Installer
Text CLI hydra-install first. List disks and provide dry-run plan by default; require explicit target and exact erase confirmation for mutation. Reject mounted or root/live-medium devices and their parent disks. No disk selected by default. Create GPT with1GiB FAT32ESP plus ext4root; unpack the prepared squashfs payload, never copy live /proc,/dev,/run. Generate fstab using UUIDs; configure chosen user, locale/timezone; remove live-only administration/autologin overrides. Generate normal disk initramfs for installed kernel; GRUB fallback EFI/BOOT/BOOTX64.EFI, without modifying host NVRAM during tests. Log operations without passwords. Errors leave a diagnostic; never continue after partition/format/copy failure.
Acceptance
Boot image in disposable OVMF/KVM VM; serial/graphical recovery available. Install to a fresh qcow2, removeISO, boot installed system, verify persisted sentinel, network and tools. Run installer negative tests for missing confirmation, mounted disks, live-source parents and unexpected lsblk data. Nested virtualization tests use their own disks; present laptop/VM disks never passed to testQEMU.
Before daily-use recommendation, laptop liveboot must validate Wi-Fi, touchpad, audio, brightness, suspend/resume, USB selection, input capture and actualdisplay refresh. Keep these as explicit pending hardware checks until observed.