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.

Updates and recovery

New images include signed runtime updates from the public repository:

hydra update check
sudo hydra update apply
hydra update status

Record the transaction printed by apply. To reverse that runtime update, use sudo hydra update rollback TRANSACTION. If the update was interrupted or the normal CLI is damaged, run sudo hydra-update-recover. See update trust, backups and limits.

After applying or rolling back, open the host shell from the terminal menu and run labwc --exit inside the Hydra graphical session. Log in again to load the new session code; running VMs keep their independent processes and disks.

Runtime updates leave the Gentoo base, kernel and guest data in place. For Portage/kernel recovery, Btrfs installations support separate offline root and EFI checkpoints made from the live ISO.

Early images lack the trusted updater and pinned key; boot/install the verified new ISO or follow the independently verified bootstrap guidance in the update documentation. Legacy local bundle recovery remains available for old test installations that already used those bundles.