Hydra-OS/README.md

HydraOS

Gentoo-based host for concurrent virtual desktops. Its default session shows one VM fullscreen and switches between guests with keyboard shortcuts. Other host desktops may use the same independent VM manager and viewers.

Status

The first installable UEFI preview passed a complete disposable QEMU/KVM run: installation, boot without the ISO, password login, persistent data, networking, nested KVM and VM survival across user logout. See the build and acceptance record. The first physical target is ASUS TUF Dash F15 FX517ZC; laptop hardware checks remain pending. Existing NixOS and VM disks were not installation or test targets.

1. Independent QEMU/KVM lifecycle with private QMP control.
2. Minimal labwc session and fullscreen SPICE viewers.
3. Gentoo rootfs, live ISO, explicit disk installer.
4. Disposable-disk installation/reboot tests, then physical live-boot checks.

Shared clipboard and directories are opt-in. VM processes survive viewer and compositor exits. GPU passthrough and graphics performance require hardware tests; a refresh-rate setting does not prove delivered FPS.

• Session design
• Implementation plan
• Hardware target

Build outputs, VM disks, runtime state and credentials stay outside Git.

First use

Follow the installation guide to install from the live ISO. The initial empty graphical session opens a recovery terminal. Enter :shell for an ordinary host shell; sudo nmtui configures host network connections. Guest operating systems are supplied by you:

hydra add work --iso /absolute/path/ubuntu.iso --memory 8192 --cpus 4
hydra start work
hydra add experiments --iso /absolute/path/gentoo.iso
hydra start experiments
exit

Back at hydra recovery>, enter :refresh to show the newly created guests. Guests remain running while you switch, reconnect viewers or leave the host graphical session. Shut a guest down from inside its OS, or request an orderly shutdown with hydra shutdown NAME. Check hydra status NAME before detaching its installer with hydra media NAME --detach and starting it again.

Shortcut	Action
Ctrl+Alt+Shift+Left / Right	Switch guest workspaces
Ctrl+Alt+Shift+Escape	Open local recovery
Ctrl+Alt+Shift+R	Release viewer input capture
Ctrl+Alt+Shift+U	Choose a USB device to redirect
Brightness keys	Adjust host backlight

New guests share hydrabr0 (10.203.0.0/24) and have distinct persistent MAC addresses. Services can communicate between guests without per-port forwarding; access from your LAN requires a router route through the HydraOS host. Each guest controls its own services and firewall. Host Internet access is separate from this local guest network.

Profiles live in ~/.config/hydra, disks in ~/.local/state/hydra; system defaults for new profiles are in /etc/hydra/defaults.toml. Use hydra --help for overrides. Other host desktops can use hydra start NAME and hydra view NAME --windowed without entering the minimal labwc session. Ordinary Gentoo administration and Portage remain available through the recovery shell.

Build the ISO

Follow the isolated Gentoo build instructions. Outputs are build/artifacts/hydra-os.iso and hydra-os.iso.sha256; binary images stay out of Git. Recorded source inputs and package versions identify the tested image. The builder uses Gentoo systemd for login/device management, labwc for the minimal graphical session, and QEMU/KVM for guests. Portage and the tracked QEMU/viewer patches remain available for ordinary updates.

Resume a build from the same source checkout and work directory used to create its builder. Moving from a worktree to another checkout requires a fresh --work directory under the project, or using the original worktree; provenance checks deliberately reject an existing container mounted to a different source.

Run the prototype

python3 -m unittest discover -s tests -v
nix-shell dev/tools.nix
bin/hydra add guest --iso /absolute/path/installer.iso
bin/hydra start guest
bin/hydra view guest
# From a dedicated graphical login; --nested uses the current graphical display.
bin/hydra session --nested

After installation, shut the guest down and run bin/hydra media guest --detach to boot its existing disk without installation media. add also supports disk-only profiles, --width, --height, and --refresh-millihz. Distribution preferences in /etc/hydra/defaults.toml affect only new profiles; explicit CLI options win.

nix-shell dev/tools.nix --run 'python3 dev/smoke.py' checks two disposable KVM counter guests and private headless viewers, including manual USB selection, reserved switching under inhibition, recovery and reconnect. See verification commands and physical checks still pending.

An empty session opens local recovery. Enter :shell, create and start guests with hydra add / hydra start, then leave the shell and enter :refresh. Refresh rebuilds workspaces and reconnects viewers for the current profiles; running VMs keep their processes and disks. Use it after adding or removing profiles. New profiles save an individual MAC address; legacy profiles obtain a stable address from their owner and disk path, including on the shared bridge.