126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# 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.
|