Hydra-OS/docs/install.md

Install Hydra OS

Hydra OS targets x86_64 UEFI systems. Disable Secure Boot for this first image. For a USB flash drive, use the 2026-10-14 corrected ISO, hydra-os-usb-fixed.iso. The original 0.2.0 ISO passed optical-media tests but has a raw USB live-boot bug. Write the corrected image to the entire flash drive using a host-native image writer; this erases that flash drive. Mounting it before reboot is unnecessary. Physical firmware compatibility still requires testing. Boot the ISO and enter :shell in the terminal VM menu. The live session uses a locked hydra-live account with local sudo access; changes in the live filesystem are volatile. The image provides no default SSH login or universal installed password.

hydra-install lists disks without selecting one. Inspect the devices, then ask for a plan using either the explicitly chosen existing partitions or a whole disk. The commands below use placeholders; the installer never chooses devices automatically.

Preserve existing partitions

Choose a root partition whose contents you intend to replace and an existing FAT GPT EFI System Partition (ESP). Inspect their identities and sizes with lsblk. Both selected partitions must be unmounted; unrelated mounted siblings are allowed.

sudo hydra-install --root-partition /dev/CHOSEN_ROOT \
  --esp-partition /dev/CHOSEN_ESP --user YOUR_USER --root-fs btrfs

This dry-run describes the operation. To execute the same choice:

sudo hydra-install --root-partition /dev/CHOSEN_ROOT \
  --esp-partition /dev/CHOSEN_ESP --user YOUR_USER --root-fs btrfs \
  --execute --confirm-format /dev/CHOSEN_ROOT

--confirm-format must name the canonical resolved root path exactly, even if an input path is an alias. This mode formats only the selected root partition. It never recreates GPT, changes partition boundaries, or formats the ESP. Before formatting, it checks uncompressed payload capacity, mounts the ESP read-only, refuses any existing EFI/HydraOS collision, and requires at least 64 MiB free. It fingerprints foreign ESP files and verifies their hashes after installation.

GRUB writes EFI/HydraOS/grubx64.efi using --no-nvram without --removable. Existing EFI loaders, EFI/BOOT/BOOTX64.EFI, and firmware BootOrder are preserved. By default, select that Hydra EFI file manually in your firmware boot interface. --register-boot-entry opts into efibootmgr --create-only: it creates a new HydraOS entry without adding it to BootOrder. Firmware support for selecting EFI files and managing entries varies.

Only plain, nonoverlapping GPT partitions on physical disks are supported. Root and ESP may reside on different disks. Device mapper, encrypted/LVM/RAID targets, nested partition devices, missing identities/bounds, active holders, and ambiguous backing information are rejected. Mounted Btrfs filesystems must report every backing member; an incomplete or missing-device report is rejected. ZFS backing anatomy is unsupported and causes a conservative refusal. The checks are repeated just before formatting; do not change mounts or storage topology during installation. They cannot replace your inspection and backups.

--root-fs ext4 is the default. Btrfs creates @root, @home, and @snapshots. The kernel, /boot, and Portage database stay inside @root; /home (including guest disks) uses @home, and /.snapshots uses @snapshots. fstab and boot arguments use filesystem UUIDs and named subvolumes, without a fixed root subvolume ID. The layout alone does not implement system rollback; full Gentoo and kernel recovery requires separate bootable verification.

An installed, root-owned mode-0600 /etc/hydra/storage.json records format 1, a random install UUID, root/ESP filesystem UUIDs and GPT PARTUUIDs, filesystem type, and owned EFI path EFI/HydraOS. Btrfs additionally records root_subvolume: "@root". Treat this identity record as installation metadata, not an update payload.

Erase a whole disk

Use this mode only when every partition on the explicitly chosen disk may be erased:

hydra-install
sudo hydra-install --disk /dev/CHOSEN_DISK --user YOUR_USER

Replace the placeholders with an actual whole disk and your desired account name. The installer rejects mounted devices, the running root, the live medium, and their backing disks. These checks help prevent mistakes; verify the chosen disk and preserve backups before executing the plan. Physical disk installation requires the operator's explicit choice.

To execute, enter the identical resolved whole-disk path in the confirmation:

sudo hydra-install --disk /dev/CHOSEN_DISK --user YOUR_USER \
  --execute --confirm-erase /dev/CHOSEN_DISK

Execution erases the disk, creates a 1 GiB FAT32 EFI partition and an ext4 root (or Btrfs with --root-fs btrfs), extracts the prepared payload, and prompts twice on the local terminal for your installed account password. Passwords have no command-line or configuration option. The installed root account stays locked. Defaults are Europe/Moscow and English UTF-8, with Russian UTF-8 also available; --timezone accepts an IANA zone present in the payload.

The installer removes the live account, local password-free sudo rule, and live autologin overrides, then builds a normal disk initramfs, its owned HydraOS UEFI loader, and a fallback UEFI loader on the newly created ESP. Both installation modes keep os-prober disabled. Wait for Installation completed, power off, remove the ISO, and boot the installed disk. Log in with the account and password you supplied. On failure, read the printed live diagnostic path; when a target root was mounted, a nonsecret snapshot is also saved at /var/log/hydra-install.log on that disk.

Disposable VM acceptance

Run the repository harness with QEMU/KVM, qemu-img, Python 3, and a generic x86_64 QEMU OVMF CODE/VARS pair. A Xen-specific OVMF build is unsuitable: the first validation attempt with that variant produced no guest boot output. Use trusted image and matching firmware files. For example:

install -d -m 700 "$HOME/.cache/hydra-tests"
python3 dev/iso-smoke.py --iso /absolute/path/to/hydra-os.iso \
  --ovmf-code /absolute/path/to/OVMF_CODE.fd \
  --ovmf-vars /absolute/path/to/OVMF_VARS.fd \
  --scratch-parent "$HOME/.cache/hydra-tests"

The harness creates a private directory under --scratch-parent (/tmp by default), a new 32 GiB sparse qcow2 disk, and a private copy of OVMF variables. There is no existing disk argument. QEMU attaches the ISO read-only; serial and QMP use private Unix sockets. Tool overrides --qemu and --qemu-img support temporary development environments. --scratch-parent, --memory, --boot-timeout, and --install-timeout control retained artifacts and bounded resource use. Prefer a disk-backed scratch directory: an installed disk stored on a tmpfs such as /tmp consumes host RAM. The example keeps test data in the user's cache.

The test boots the live image, runs the real installer through the guest's controlling terminal using a generated password, writes a persistence sentinel, shuts down, and launches a second QEMU with the ISO absent. It verifies password login, disk root, removed live overrides, services, bridge/NAT configuration, DNS, recovery tools, and a routed new TCP connection from a synthetic LAN to a synthetic VM endpoint. Network namespaces and veth interfaces exist only inside the disposable Hydra OS guest. When guest KVM is available, it launches a further fresh-disk QEMU as the installed account to exercise KVM, the bridge helper, and private QMP; this checks VM launch, not a nested operating system boot. The installed normal account also exercises the packaged terminal menu, downloads a complete nonboot ISO fixture from a private loopback HTTP server, starts a scratch VM with hydra run, checks cache reuse and stable process/QMP identity through hydra open, and verifies the default Fastfetch logo/name. This fixture checks the command flow, not a nested guest OS boot.

The harness also logs the installed account out and back in, checking that the same VM, private sockets and user audio services survive a measured interval without an open login session. This establishes process/socket continuity, not audio playback.

report.json records each observed check, ISO/firmware SHA256, failures, and skipped nested virtualization. Serial/QEMU logs and the qcow2 remain in the printed scratch directory for review; passwords are redacted even across serial read boundaries. Cleanup controls only the QEMU process created by this run. A passing unit suite establishes harness behavior, not ISO acceptance. An actual successful report from the built ISO is required for boot/install/reboot acceptance.

Checks requiring the laptop

Disposable QEMU results cannot establish ASUS FX517ZC hardware support. Before using Hydra OS daily, boot the live ISO and observe Wi-Fi, touchpad, audio, brightness, suspend/resume, USB device selection, input capture, and actual display refresh. Physical installation and these checks remain pending until explicitly performed and recorded.