docs (talos hvm): add the requirements and run your first virtual mac…

[Iheanacho-ai]

What

Adds the Getting Started section for Talos Hypervisor:

• requirements.mdx: host hardware, host software (Talos Linux v1.15 or later and the libvirtd system extension), and client requirements.
• install-a-hypervisor-host.mdx: build an Image Factory schematic with the libvirtd extension, install Talos Linux with that installer image, add the /etc/passwd and /etc/group files the extension needs, and check that ext-virtqemud is running.
• run-your-first-virtual-machine.mdx: create a content library, upload a Talos Linux ISO, declare a virtual machine that boots from it, check its status, connect to Talos Linux running in the virtual machine, and clean up. A section explains what other ISOs need.

Why

This is part of the Talos Hypervisor docs for TalosCon. It builds on the navigation in #805, and the combined PR at the end will bring all of the Talos Hypervisor PRs to main.

Change

• public/hypervisor/getting-started/requirements.mdx: new page.
• public/hypervisor/getting-started/install-a-hypervisor-host.mdx: new page. A TODO comment marks the EtcFileConfig step, pending confirmation from engineering on whether it stays a manual step.
• public/hypervisor/getting-started/run-your-first-virtual-machine.mdx: new page.

Testing

• Ran: make style-check-changed. Every Talos machine configuration YAML block was loaded and validated with Talos's own config loader and validator, which also rejected deliberately broken versions. The vm.yaml and $patch: delete files were applied as patches with Talos's patch loader, given as bare file names.
• Where: local checkout, against siderolabs/talos main at 4194ca1 and siderolabs/extensions main at 7d75c4b
• By: an agent (Claude Code), plus separate agents that fact-checked the pages against the source, citing file:line
• Result: the style check passes and every YAML block validates. The first fact-check (requirements and the first version of the run page) found one wrong claim and three gaps, all corrected. A second fact-check covers the install page and the run page after its example changed to a Talos Linux guest. The commands have not been run on a host, because there is no Talos v1.15 alpha build yet, and they need a run on the alpha before the combined PR merges. The frontmatter check reports the pages as belonging to no known section until docs (talos hvm): add the Talos Hypervisor navigation structure #805 merges.
• Filled from outside the page: details confirmed with engineering on Slack on 2026-10-06: Image Factory offers the libvirtd extension from Talos 1.15, virtual machines run on Kubernetes nodes, and hypervisor hosts use the /etc/passwd and /etc/group EtcFileConfig documents (whether this stays required is still being confirmed). The run example follows the tested flow in feat: provision VM disk from iso (content library) talos#14499. The hardware virtualization requirement (Intel VT-x or AMD-V) and the guidance under Using a different ISO come from general knowledge, not the Talos source.

[github-actions]

📋 Automated documentation review

An automated pass runs on documentation changes in every PR. The items below are suggestions to consider — advisory, not a merge gate.

Reviewed commit 56a849e · 🔴 4 critical · 🟡 1 warning(s) · ⚪ 1 notice(s)

• 🔴 public/hypervisor/getting-started/install-a-hypervisor-host.mdx:87 — talosctl --patch needs an @ prefix to read a patch from a file
  • Why: talosctl's --patch flag takes patch contents, not a path; a file is only read with the @ prefix (upstream patch.go implements --patch-file by prepending "@"). As written the command errors instead of applying the EtcFileConfig documents, so /etc/passwd and /etc/group are never created and ext-virtqemud and ext-virtstoraged, which depend on those paths, never start.
  • Fix: talosctl patch machineconfig --nodes --patch @hypervisor-users.yaml
• 🔴 public/hypervisor/getting-started/run-your-first-virtual-machine.mdx:57 — talosctl --patch needs an @ prefix to read a patch from a file
  • Why: Without the @ prefix talosctl parses the literal string content-library.yaml as the patch and fails, so the UserVolumeConfig and ContentLibraryConfig documents are never applied and the following talosctl get contentlibrarystatuses returns nothing.
  • Fix: talosctl patch machineconfig --nodes --patch @content-library.yaml
• 🔴 public/hypervisor/getting-started/run-your-first-virtual-machine.mdx:120 — talosctl --patch needs an @ prefix to read a patch from a file
  • Why: Without the @ prefix the command errors instead of applying vm.yaml, so the VirtualMachineConfig is never added and no virtual machine is created.
  • Fix: talosctl patch machineconfig --nodes --patch @vm.yaml
• 🔴 public/hypervisor/getting-started/run-your-first-virtual-machine.mdx:168 — talosctl --patch needs an @ prefix to read a patch from a file
  • Why: Without the @ prefix the cleanup patch is never applied, so the reader believes the virtual machine was deleted while it is still declared and running, and the subsequent content-library delete fails because the ISO is still in use.
  • Fix: talosctl patch machineconfig --nodes --patch @vm-delete.yaml
• 🟡 public/hypervisor/getting-started/requirements.mdx:32 — Refers to a console-history command that does not appear to exist
  • Why: The v1.15 CLI reference lists only talosctl hypervisor console and talosctl hypervisor content-library, and the console help states it does not replay previous console output; no console-log resource exists under pkg/machinery/resources/hypervisor. Readers may hunt for a command that is not there.
  • Fix: Attaching to a virtual machine's serial console requires the Admin role in your talosconfig and targets one node at a time; talosctl hypervisor console attaches to the live console only and does not replay earlier output. It is available on macOS and Linux clients, but not on Windows.

Notices, and the reviewer's full report, are in the run's doc-accuracy-report artifact.

[github-actions]

📋 Automated documentation review

⚠️ The reviewer did not finish on commit ab8aeed (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

[frezbo]

not sure if we need to mention this, since later we would have more support

[Iheanacho-ai]

removed the note

[sterlingkoch]

Merged as part of #867.