# 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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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](updates.md).

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](system-recovery.md) 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](legacy-runtime-update.md) remains
available for old test installations that already used those bundles.