feat: add systemd-machined integration and SSH over VSOCK

[elsbrock]

Adds systemd-machined integration and SSH over VSOCK support for MicroVMs.

machined integration

microvm.registerWithMachined = true registers VMs with machined:

$ machinectl list
MACHINE    CLASS SERVICE     OS VERSION ADDRESSES
authelia   vm    microvm.nix -  -       -
blackpearl vm    microvm.nix -  -       -

• machinectl list/status/show for visibility
• machinectl terminate/kill to stop VMs

This PR prefers RegisterMachineEx on systemd 259+ and falls back to legacy machined calls on older hosts.
When available, it registers VSockCID / SSHAddress metadata (plus network interfaces).

machinectl reboot/poweroff/terminate/kill all stop the VM without auto-restart (systemd treats signals from machined as intentional stops). Use systemctl restart microvm@<name> for restarts.

SSH over VSOCK

microvm.vsock.ssh.enable = true configures guest sshd to listen on VSOCK (requires microvm.vsock.cid):

$ microvm -s myvm
Connecting to myvm via VSOCK...
[myvm]$

Works with qemu/crosvm/kvmtool (native AF_VSOCK) and cloud-hypervisor (socket mux).

This PR also updates microvm -s argument handling so SSH options can be forwarded via --, e.g.:

• microvm -s myvm -- -l root -i /path/to/key

Other changes

• microvm -l respects configured microvm.stateDir
• microvm.machineId option for consistent UUID handling across machined/SMBIOS/guest machine-id use
• QEMU shutdown script handles missing control socket (fixes restart after external kill)
• imperative microvm@%i template tolerates missing microvm-register / microvm-unregister scripts

Tests

• expands machined test coverage for VM metadata (VSockCID, SSHAddress) where applicable
• adds a focused microvm -s argument-handling test
• adds imperative template test for start/stop without register scripts

Closes #123

[elsbrock]

Thanks for the review! Force pushed with two fixes from testing:

• Added coreutils to PATH in register script (was missing tr)
• Changed test to check Leader property instead of machinectl kill --signal=0 (not supported)

machined-qemu tests pass now.

[elsbrock]

Sorry, quite busy. Will have another look over the weekend.

[Copilot]

Pull request overview

Adds host/guest integration features for MicroVMs by registering VMs with systemd-machined (enabling machinectl visibility/control) and enabling SSH access over VSOCK, plus a small QEMU shutdown robustness tweak.

Changes:

• Extend the microvm host CLI with -s to SSH into a running VM via VSOCK and respect a configurable stateDir.
• Add registerWithMachined + machineId options and generate/register machined metadata from the runner.
• Add a NixOS test covering machined registration, and filter check variants by host platform/hypervisor support.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
pkgs/microvm-command.nix	Adds stateDir parameter, includes openssh, and implements microvm -s VSOCK SSH wrapper.
nixos-modules/microvm/vsock-ssh.nix	New guest module option to enable sshd for VSOCK connectivity.
nixos-modules/microvm/system.nix	Initializes guest /etc/machine-id and derives networking.hostId from microvm.machineId.
nixos-modules/microvm/options.nix	Adds registerWithMachined and machineId options.
nixos-modules/microvm/default.nix	Wires in the new vsock-ssh module.
nixos-modules/host/default.nix	Passes stateDir into the microvm CLI package; hooks machined register/unregister scripts into VM services.
lib/runner.nix	Generates machined register/unregister scripts; writes VSOCK CID + hypervisor metadata to runner output.
lib/runners/qemu.nix	Passes machine UUID via SMBIOS; makes shutdown script tolerate missing control socket.
checks/machined.nix	Adds a nixosTest validating machined registration and basic machinectl operations.
checks/default.nix	Filters the checks matrix to only hypervisors supported on the current platform.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[elsbrock]

Pushed an update that should cover the open points.

• switched machined registration to use RegisterMachineEx on systemd 259+ (with fallback to old calls)
• fixed the UUID byte conversion (strtonum($i))
• passed VSockCID / SSHAddress where applicable
• fixed microvm -s arg handling so -- can be used for ssh opts
• made microvm@%i tolerate missing register/unregister scripts in imperative mode
• updated microvm.machineId docs to match actual behavior
• applied the replaceString "-" "" cleanup for machine-id

Also added targeted tests for this:

• machined metadata checks
• microvm -s arg parsing
• imperative template behavior without register scripts

Ran these locally:

• nix build .#hydraJobs.x86_64-linux.microvm-command
• nix build .#hydraJobs.x86_64-linux.imperative-template
• nix build .#hydraJobs.x86_64-linux.machined-qemu
• nix build .#hydraJobs.x86_64-linux.machined-cloud-hypervisor

All green here.

[SuperSandro2000]

I am going to push the final bits in this PR to get this merged.

[SuperSandro2000]

[root@storage1:~]# microvm -s librenms
Connecting to librenms via VSOCK...
Warning: Permanently added 'vsock/3597670762' (ED25519) to the list of known hosts.

  ______    ______
 / / / /   / /\ \ \
/ / / /   / /  \ \ \
\ \ \ \  / /   / / /
 \_\_\_\/_/   /_/_/

Last login: Sun Mar  8 18:50:48 2026 from 2a02:3100:2488:4500:2be6:4a66:e121:7468

[root@librenms:~]#

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

doc/src/faq.md:31

• The markdown code fence around the microvm.shares = [...] example is now unbalanced: there’s a closing but no openingnix before the snippet. Add the opening fence (or remove the closing one) so the rest of the FAQ renders correctly.

microvm.shares = [ {
  # On the host
  source = "/var/lib/microvms/${config.networking.hostName}/journal";
  # In the MicroVM
  mountPoint = "/var/log/journal";
  tag = "journal";
  proto = "virtiofs";
  socket = "journal.sock";
} ];

</details>



---

💡 <a href="/microvm-nix/microvm.nix/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.<br><br>You can also share your feedback on Copilot code review. [Take the survey](https://www.surveymonkey.com/r/XP6L3XJ).

[SuperSandro2000]

One thing I noticed: the microvm-register script is not very robust and if the vm crashes early on, it may cannot be re-run, but since this is a new, by default off, feature, I am going fine with it, but we should improve that in the future and in another PR.

[oddlama]

if a user sets machineId = null this will error out. should probably be guarded with mkIf machineId != null

[SuperSandro2000]

I've opened #499, but I only eye balled this, so it could be another issue like this in the code base.

[oddlama]

This default bit me when updating, as it overwrote the generated machine-id that was in use previously (which caused a lot of dependent failures). This change is a breaking change for existing declarative instances

[SuperSandro2000]

I do not have a good idea how to make this migration smooth unless we introduce a state version.