ya-runtime-vm

A virtual machine runtime that lets Golem Network providers run Linux task images in isolated VMs.

• One self-contained executable: OpenVMM is embedded, so no QEMU, firmware or separate VMM is installed.
• Linux and Windows hosts: KVM on Linux, Windows Hypervisor Platform (WHP) on Windows, running x86_64 Linux guests.
• Golem tasks: GVMI images, stdout/stderr streaming, host directory shares, storage and RAM volumes, Yagna VPN and INET networking.

Supported platforms

Host	Hypervisor	VM tests in CI	PCI passthrough
Linux x86_64	KVM	Yes	Yes (VFIO)
Windows x86_64	WHP	Manual (procedure)	No

Install

Download a package from GitHub Releases.

On Debian or Ubuntu, install the .deb; it places the runtime under /usr/lib/yagna/plugins/:

sudo apt install ./ya-runtime-vm_*_amd64.deb

Otherwise, extract the Linux .tar.gz or Windows .zip and copy ya-runtime-vm.json and the ya-runtime-vm/ directory into the provider's plugin directory. The provider uses the first of plugins/ beside its executable, ~/.local/lib/yagna/plugins/ (a golemsp installation) and /usr/lib/yagna/plugins/; EXE_UNIT_PATH overrides this. Keep the executable and its runtime/ directory together.

The host needs hardware virtualization:

• Linux: read/write access to /dev/kvm, usually through the kvm group, and KVM support for KVM_CAP_ENFORCE_PV_FEATURE_CPUID. Startup fails if this capability is unavailable; see the enforced PV policy.
• Windows: the Windows Hypervisor Platform feature, then a reboot: Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform.

Check the installation with the self-test, which boots a VM, runs a bundled task and prints its JSON result:

./ya-runtime-vm test

How it works

The exe-unit drives the runtime through the Yagna runtime API. The runtime boots the Linux kernel directly and controls a Rust guest agent, running as PID 1, over virtio-vsock. See Architecture for details.

flowchart LR
  exe[Yagna exe-unit] -- runtime API --> rt[ya-runtime-vm + OpenVMM]
  rt -- virtio-vsock --> agent[Guest agent, PID 1]
  rt -- virtio-blk / virtio-fs / virtio-net --> guest[Linux guest]
  agent --> tasks[Task processes]

Loading

Build from source

Install mise for the pinned toolchain. On a Linux host with Docker and build-essential perl musl-tools:

mise trust && mise install
mise run build-release
mise run guest-image
mise run fetch-self-test
mise run package

Packages are written to releases/. Windows builds, Debian packages and requirements are covered in Building and packaging.

Documentation

• Building and packaging
• Architecture: guest agent, process lifecycle, repository layout
• Volumes and host directories: share policy and limits
• Networking: VPN and INET interfaces and their MTUs
• Testing and troubleshooting
• Windows/WHP test procedure
• virtio-fs security review

Security

Report vulnerabilities privately through GitHub security advisories, not in public issues.

License

ya-runtime-vm is licensed under GPL-3.0. Packages include THIRD-PARTY-NOTICES.txt with the licenses of bundled components and links to their sources, including the guest Linux kernel and BusyBox.