Hydra-OS/docs/releases/2026-10-13-laptop-ready/README.md

# Hydra OS 0.2.0 — installation, updates and recovery

**The source suite passed 431 tests. The final ISO passed 13 whole-disk checks
and 23 preserved-partition/recovery checks. No acceptance check was skipped.**

Hydra OS is a Gentoo host for concurrent virtual desktops, with a minimal labwc
session and terminal controls. This release adds installation into selected
partitions, signed runtime updates, offline Btrfs base recovery and read-only
laptop diagnostics.

## Verification

| Item | Final result |
| --- | --- |
| Image and runtime source | `ebeebc7fb1aed07a5f50bc62374365d614953dad` |
| ISO | `hydra-os.iso`, 2,380,406,784 bytes |
| ISO SHA-256 | `451e058228d7cbea87b5301ae6502b6be609cf7f52cc7c9e6fb477822501389b` |
| Signed runtime | Version `0.2.0`, sequence `1` |
| Complete source suite | `431` passed in `26.048` seconds |
| Whole-disk UEFI/KVM acceptance | 13 passed; 0 skipped |
| Preserved-partition/recovery UEFI/KVM acceptance | 23 passed; 0 skipped |

Independent final integration review found no actionable issues and verified all
19 signed runtime payload files against source bytes/modes and the pinned key.

The final [artifact record](artifacts.json), [whole-disk report](whole-disk-acceptance.json)
and [laptop report](laptop-acceptance.json) identify the exact ISO, firmware and
harnesses. The [image audit](image-audit.json) checks packaged files, including the
independent updater and pinned key, against source hashes and required ownership
and modes. The [rootfs manifest](rootfs-manifest.json) records source inputs and
package versions; [Fastfetch](fastfetch.txt) captures the final installed guest.

Final acceptance uses fresh private virtual disks and the final ISO. Earlier
diagnostic runs against an older ISO do not establish this release's acceptance.
Both installed boot sequences remove ISO media. The laptop sequence checks GPT
boundaries, foreign partition bytes and foreign/fallback EFI bytes across all
boots. It checks BootOrder immediately around installation, checkpoint, restore
and each deliberate boot-selection operation. OVMF may prune an empty DVD entry
between boots; the report does not claim identical BootOrder across reboots.

## Installation and recovery

Existing-partition installation formats only the selected root partition and
retains the existing ESP. It supports ext4 or Btrfs; Btrfs uses `@root`, `@home` and
`@snapshots`. From the live ISO's `:shell`, inspect the devices and request a plan:

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

These are placeholders; no physical target partition has been selected. Execution
requires `--execute --confirm-format /dev/CHOSEN_ROOT`. The ESP needs room for
`EFI/HydraOS`; select its `grubx64.efi` loader in firmware, or explicitly request
`--register-boot-entry` to create an entry without changing BootOrder. See the
[installation guide](../../install.md).

Boot the trusted live ISO with the installed filesystems unmounted to create or
restore a Btrfs checkpoint:

```sh
sudo hydra-system checkpoint --root-uuid ROOT_UUID --esp-partuuid ESP_PARTUUID \
  --name before-update --execute --confirm-root-uuid ROOT_UUID
sudo hydra-system list --root-uuid ROOT_UUID
sudo hydra-system restore --root-uuid ROOT_UUID --checkpoint CHECKPOINT_ID \
  --execute --confirm-root-uuid ROOT_UUID
```

Omit execution and confirmation options to inspect a plan first. Recovery restores
the root, kernel, Portage state and owned EFI loader together. Current HOME and VM
data stored there remain unchanged. An interrupted restore resumes with the same
checkpoint ID. Acceptance upgrades a local Portage fixture, damages the actual
kernel/owned loader, sends SIGKILL after a durable restore transition, resumes in
a fresh process, then verifies exact restored base hashes and boots without ISO.
This proves exact kernel restoration, not an upgrade between two kernel versions.

Checkpoints share the original disk and are not external backups. Restoring the
root also restores runtime update receipts and their replay floor. See
[base recovery](../../system-recovery.md).

## Updates and diagnostics

```sh
hydra update check
sudo hydra update apply
hydra update status
sudo hydra update rollback TRANSACTION
sudo hydra-update-recover
hydra doctor
```

The [signed runtime manifest](../../../releases/stable/manifest.json) describes a
passive payload verified against the image's independently pinned Ed25519 key.
The public repository serves the release without a separate update server.
The standalone recovery command works independently of a damaged normal CLI.
Acceptance uses a disposable TEST key in its private guest, refuses a tampered
archive, and verifies apply, rollback and fresh-process recovery after SIGKILL.
The original pinned key is restored afterward.

The payload updates Hydra runtime and branding. Gentoo packages/kernel, networking,
guest data, the updater engine and its trust key are outside its scope. Log out
and in after applying or rolling back to load changed session code. Older images
without the trusted updater need a verified new image or a separately verified
bootstrap. See [update scope and trust](../../updates.md).

`hydra doctor` reports observations without changing settings. Physical ASUS
FX517ZC checks remain pending: live boot, Wi-Fi/Ethernet, audio playback, touchpad
and input capture, brightness, USB, suspend/resume and delivered display refresh.
The first image requires Secure Boot disabled. No physical disk, existing NixOS
installation or existing user VM disk was an installation target. VM acceptance
does not establish physical graphics performance or audio playback.

See [acceptance instructions](../../laptop-acceptance.md) to repeat both harnesses
with the recorded source, ISO and firmware inputs. ISO files, test disks, private
build records and raw logs remain outside Git; this directory contains the
public verification record.