97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
# 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
|
|
|
|
Under active development, not yet an installation-ready distribution. The target
|
|
is an installable UEFI ISO, first validated on ASUS TUF Dash F15 FX517ZC. Existing
|
|
NixOS and VM disks are 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 initial empty graphical session opens a recovery terminal. Enter `:shell`
|
|
for an ordinary host shell; `nmtui` configures the host's network connections.
|
|
Guest operating systems are supplied by you:
|
|
|
|
```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 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.
|
|
|
|
## 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.
|