Using Hydra OS from the terminal

Hydra OS keeps the host small. Virtual machines have independent disks and processes; closing a screen or the host menu does not power them off.

Open a machine

The initial session shows the VM menu. Enter a number or a VM name. Enter alone uses the last selection when it still exists, or the only configured VM. A stopped VM starts; an already running one reconnects. Ctrl+Alt+Shift+Escape opens the menu while working inside a VM, and Ctrl+Alt+Shift+Left/Right switch between VM workspaces.

An ordinary terminal or SSH session can use:

hydra open work
hydra start work
hydra status work
hydra shutdown work

open requires a graphical display unless --no-view is supplied. start and shutdown are the existing explicit lifecycle commands. Shutdown requests an orderly guest poweroff; it does not promise instantaneous completion.

Download and run an installer

Use a direct .iso download URL supplied by the distribution:

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

Replace the example URL. The command downloads a validated image, creates a new profile, starts that VM and opens its screen. Existing names are refused before downloads or disk changes; use hydra open work next time. The same command accepts a local ISO path. Use --no-view to run without a viewer.

To download without creating a machine:

hydra download 'https://example.org/distribution.iso'

Add --sha256 followed by the publisher's 64 hexadecimal digits to check the download. Format validation alone checks that the file looks like an ISO, not who published it. Validated files are cached under ~/.cache/hydra/iso (or $XDG_CACHE_HOME/hydra/iso). Ctrl+C cancels an active download without publishing its partial file. HTTP is available for a local test transfer; prefer the publisher's HTTPS endpoint for Internet downloads.

The guest OS installer still performs installation inside its virtual disk. After it finishes, shut the guest down, detach the installer and reopen it:

hydra shutdown work
hydra status work
# Wait until status is stopped:
hydra media work --detach
hydra open work

This avoids accidentally booting the live ISO again. No guest disk is recreated.

Network and host controls

The menu offers host shell and network actions. sudo nmtui controls the physical host's Wi-Fi/Ethernet connections. Guests see virtual Ethernet and receive Internet access through Hydra; they do not each select the Wi-Fi SSID. When testing Hydra inside another VM, physical Wi-Fi remains controlled by the outer host (currently NixOS).

The guest bridge uses 10.203.0.1/24. A guest can SSH to 10.203.0.1 after SSH service and authentication have been configured on Hydra. An SSH login is not enabled automatically. Networking between Hydra and its guests does not require Internet access. VPN clients can run in individual guests; a shared host VPN requires routing guest traffic through that VPN explicitly.

If something fails

Download returns HTML: copy the actual ISO link, not its web download page.
A checksum mismatch: do not boot that download; verify the source/checksum.
A missing ISO: attach a valid image, or detach installation media after the guest was installed and stopped.
Insufficient RAM: stop an unused VM or choose a smaller guest allocation. The launch check reserves 768 MiB on Hydra. A nested Hydra cannot see memory pressure on the outer NixOS host; leave headroom there too.
A viewer closes: reopen the VM. Closing a viewer does not erase its disk or stop its running workloads.
An unknown VM state: inspect the reported error/QEMU log. Hydra will not blindly start a duplicate or signal a process whose identity it cannot verify.

Run fastfetch for the host summary and Hydra OS logo. Advanced administration remains ordinary Gentoo administration from the host shell.

Update an existing test installation

The first ISO predates this interface. A runtime bundle updates the Hydra program and branding files while retaining the original image manifest and backing up replaced files under /var/lib/hydra/updates. It leaves VM profiles, disks, the kernel and network configuration in place. To build one from a trusted checkout:

python3 dev/guest-update.py --build . --output /tmp/hydra-os-update.pyz

Copy the resulting file into Hydra, then inspect and apply it inside Hydra:

python3 hydra-os-update.pyz
sudo python3 hydra-os-update.pyz --apply

The first command only prints the file inventory. After applying, log out of Hydra's graphical session and log in again so the long-running session process loads the new code. Reopening a terminal alone cannot reload that process. Running VMs remain independent of the graphical session.

This bundle contains the Fastfetch configuration and logo, but no executable packages. If the old installation lacks Fastfetch, install it inside Hydra:

sudo emerge --getbinpkg --noreplace app-misc/fastfetch

5.0 KiB Raw Blame History