Hydra-OS/docs/terminal-usage.md

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. Supported images are ISO9660 and ISO9660/UDF hybrids; pure UDF images are currently refused because their completeness cannot be validated. Format validation checks the declared ISO9660 volume fits the file; it does not verify the publisher or optional trailing hybrid data. 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, open the current Hydra recovery terminal with Ctrl+Alt+Shift+Escape, enter :shell, then run this command inside that installed Hydra graphical session:

labwc --exit

At the login screen, log in again as the same Hydra user. This restarts the long-running session process with the updated code. Use this from the recovery shell, not an SSH login or the outer host terminal. Reopening a terminal alone cannot reload that process. Running VMs remain independent of the graphical session.

To reverse a successful update, or finish recovery after a reported partial rollback, use the exact retained backup path printed by the updater. Correct the reported filesystem problem first. Inspect its records inside Hydra:

backup='/var/lib/hydra/updates/REPLACE_WITH_THE_REPORTED_BACKUP'
sudo python3 -m json.tool "$backup/backup.json"

Process every listed path relative to /. For an entry with "existed": true, restore that path from the same relative location in the backup. For example, after confirming the CLI entry originally existed:

relative='usr/lib/hydra/hydra/cli.py'
sudo cp --no-dereference --remove-destination --preserve=mode,timestamps -- "$backup/$relative" "/$relative"

Use the same operation for other originally existing files. When "symlink" is recorded, restore the symlink itself with this command; do not copy its referent. In particular, restoring etc/os-release must recreate its recorded vendor symlink while leaving /usr/lib/os-release intact. Check the restored link with readlink /etc/os-release and compare it to backup.json.

For each entry with "existed": false, remove only that exact installed file using sudo rm -f -- /THE_RECORDED_RELATIVE_PATH; no backup copy exists for it. This includes newly added modules, logos or the runtime-update receipt when listed as originally absent. Copying the backup directory over / alone will leave these additions behind. Confirm restored regular-file modes and SHA-256 values against their records, retain the backup, then exit the Hydra graphical session and log in again as described above.

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