# Hydra OS

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

Hydra OS 0.2.0 adds selected-partition installation, signed runtime updates,
offline Btrfs base recovery and read-only laptop diagnostics. The complete source
suite passed **431 tests**. The final ISO passed **13 whole-disk** and **23
preserved-partition/recovery** UEFI/KVM checks, with no skips. See the
[release and acceptance record](docs/releases/2026-10-13-laptop-ready/README.md).
The [previous terminal UX preview](docs/releases/2026-10-13-terminal-ux/README.md)
passed 13 disposable UEFI/KVM checks against its earlier image. The first physical
target is ASUS TUF Dash F15 FX517ZC; hardware checks remain pending. No physical
partition has been selected, and existing NixOS and VM disks were not 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](docs/superpowers/specs/2026-10-13-graphics-session-design.md)
- [Implementation plan](docs/superpowers/plans/2026-10-13-graphics-session.md)
- [Hardware target](docs/hardware/asus-fx517zc.md)
- [Signed runtime updates](docs/updates.md)
- [Offline Gentoo base recovery](docs/system-recovery.md)

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

## First use

Follow the [installation guide](docs/install.md) to install from the live ISO.
The session opens a terminal VM menu. Choose a machine by number or name;
Enter opens the remembered selection, or the only machine. Opening a stopped
machine starts it; opening a running one reconnects its screen. Merely opening
the menu does not start every VM. `:shell` opens an ordinary host shell and
`:network` opens NetworkManager's connection menu. The existing VM disks and
command-line controls remain available.

From a Hydra shell, a direct installer URL can become a running VM in one
command. Replace the example URL with an actual ISO download link:

```sh
hydra run 'https://example.org/distribution.iso' --name work --memory 4096 --cpus 2
hydra open work
```

`run` also accepts a local ISO path. It refuses to replace an existing VM name;
use `open` for subsequent starts. Add `--no-view` for a headless launch. A
download-page URL returning HTML is rejected. Downloads show progress, can be
cancelled with Ctrl+C, and become reusable cache entries only after validation.
Supply the publisher's SHA-256 when available:

```sh
hydra download 'https://example.org/distribution.iso' --sha256 PUBLISHER_SHA256
```

The cache lives under `$XDG_CACHE_HOME/hydra/iso` (normally
`~/.cache/hydra/iso`). Without a publisher checksum, ISO format validation
does not establish publisher authenticity. New launches through this workflow
check available RAM with a 768 MiB host reserve; this cannot guarantee against
later memory pressure. In a nested test, leave RAM available on the outer host
too. The original lower-level commands remain useful for manual control:

```sh
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 in the terminal menu, select the new guest to open its screen.
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 the terminal VM menu |
| 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 Hydra OS 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.

Fastfetch displays the **Hydra OS** system summary and its custom terminal
logo. It is included in the new image; the first published ISO predates this
interface update. See [terminal usage](docs/terminal-usage.md) for networking,
installation media and common recovery steps.

## Build the ISO

Follow the [isolated Gentoo build instructions](image/README.md). Outputs are
`build/artifacts/hydra-os.iso` and `hydra-os.iso.sha256`; binary images stay out
of Git. [Recorded source inputs and package versions](docs/releases/2026-10-13-laptop-ready/rootfs-manifest.json)
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

```sh
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](docs/verification.md).

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.