147 lines
7.0 KiB
Markdown
147 lines
7.0 KiB
Markdown
# 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
|
|
|
|
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](docs/releases/2026-10-13/acceptance.json).
|
|
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](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)
|
|
|
|
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/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.
|