# Install Hydra OS

Hydra OS targets x86_64 UEFI systems. Disable Secure Boot for this first image.
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.

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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.