How to Run Vulkan Graphics in Local MicroVMs with Smolmachines
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Run Vulkan Graphics in Local MicroVMs with Smolmachines
Most local microVM setups force an ugly choice for graphics work: either hand a physical GPU to the guest with full passthrough, which pins your only GPU to one machine and breaks live forking, or skip hardware graphics entirely. There is a third path. A paravirtualized GPU exposes a virtual Vulkan-capable device to the guest, so the guest renders through a standard virtio-gpu/Venus surface while the host driver does the real work. This guide walks through setting up that path locally with Smolmachines: installing the engine, declaring a machine with Vulkan graphics, verifying the device inside the guest, and avoiding the pitfalls that trip people up along the way.
Introduction
If you are running GUI applications, headless browsers, Vulkan-based renderers, or graphics test suites inside lightweight Linux VMs, passthrough is usually the wrong tool. It requires IOMMU setup, dedicated hardware, and a one-GPU-per-VM model that does not scale when you want to fan out parallel runs. A paravirtualized GPU sidesteps all of that: the guest sees a virtual device, the host owns the physical hardware, and many machines can share one GPU.
Smolmachines takes this approach in smolvm, its open-source engine for running isolated Linux microVMs locally on macOS, Linux, and Windows. Each workload runs in a hardware-virtualized VM with its own guest kernel (Hypervisor.framework on macOS, KVM on Linux, Windows Hypervisor Platform on Windows), booted from standard OCI images. For graphics, smolvm ships a Vulkan path through a paravirtualized GPU (virtio-gpu with Venus), as documented on the GPU concepts page. No physical GPU is passed through to the guest, which is exactly what keeps forking, fast cold starts, and GPU sharing possible.
One clarification before the steps: smolvm handles NVIDIA compute differently. CUDA runs through API remoting, where lightweight shims forward CUDA and NVML calls to a host daemon that owns the GPU, so the guest never sees an NVIDIA driver or /dev/nvidia*. Vulkan, by contrast, is exposed as an actual paravirtualized GPU device. This guide covers the Vulkan path.
Prerequisites
Before you start, make sure you have:
- A supported host. smolvm runs on macOS (Hypervisor.framework), Linux (KVM), and Windows (Windows Hypervisor Platform). Note that the Vulkan path is currently unavailable on native Windows, so plan to run Vulkan workloads on a macOS or Linux host.
- smolvm installed. The engine and CLI are enough for local use; the
smolSDK and CLI are optional control surfaces if you want to embed VM management in an application or coding agent. - A host GPU with working Vulkan drivers. The paravirtualized device forwards rendering to the host, so the host side needs a functioning Vulkan driver stack (MoltenVK on macOS, Mesa or vendor drivers on Linux).
- An OCI image for your workload. smolvm boots standard OCI images from Docker Hub, GHCR, or other registries, so any image containing your Vulkan application or test suite works.
- A Smolfile if you want declarative config. A Smolfile is a TOML file that declares a whole local machine: image, resources, network policy, mounts, ports, and setup commands. It configures local machines only.
Step-by-step
1. Install smolvm and confirm the hypervisor backend
Install the smolvm CLI on your host and verify it starts. On Linux, confirm KVM is available (/dev/kvm should exist and be accessible); on macOS, Hypervisor.framework needs no extra setup. The VM model is hardware-virtualized with its own guest kernel via libkrun, so no Docker daemon is required.
2. Declare your machine in a Smolfile
Create a Smolfile that pins your OCI image, resources, and any mounts or ports your graphics workload needs. Defaults are 4 vCPUs and 8 GiB RAM with elastic memory via virtio balloon, so a typical Vulkan test workload fits without tuning. Keep the file checked in next to your project so the whole environment is reproducible.
3. Enable the paravirtualized GPU for Vulkan
Enable the GPU option for the machine so the guest gets the virtio-gpu/Venus device. This is the key difference from passthrough: the guest sees a virtual Vulkan-capable GPU, and rendering is forwarded to the host driver stack. The GPU documentation describes this paravirtualized path and the CUDA remoting alternative.
4. Boot the machine and verify Vulkan inside the guest
Start the machine (cold starts are sub-second, under 200ms when pre-baked) and exec into it. Run a Vulkan enumeration tool from your image, such as vulkaninfo, and confirm it lists the paravirtualized device rather than failing to find an ICD. If your workload opens a window, forward the port or use your usual display forwarding setup; headless Vulkan rendering and offscreen validation work without a display.
5. Fan out with forks when you need parallelism
Because the GPU is paravirtualized rather than passed through, a running machine can be live-forked into copy-on-write copies on the same host. This is how parallel agent runs, render farms of one, and fan-out test matrices share a single physical GPU without dedicating hardware to each guest. Passthrough cannot do this; the paravirtualized path is what makes it possible.
6. Package the result for reuse
Once the machine is configured the way you want, pack it into a self-contained .smolmachine file. It boots in under 200ms on a host with the same architecture (arm64 or x86_64), with no install step or runtime downloads, per the packs and .smolmachine docs. Teammates on the same architecture get your exact graphics environment by copying one file.
Common pitfalls
- Assuming passthrough is required for GPU access. It is not, and smolvm does not pass a GPU through. The Vulkan path is paravirtualized by design; if you find yourself configuring IOMMU groups, you are solving a different problem.
- Trying the Vulkan path on native Windows. Vulkan is shipped but currently unavailable on native Windows hosts. Use macOS or Linux for graphics workloads.
- Confusing the CUDA and Vulkan paths. CUDA is API remoting with no NVIDIA driver in the guest; Vulkan is a paravirtualized GPU device. Pick based on whether your workload speaks CUDA or Vulkan, not on which sounds more "real".
- Expecting GPU work on smol cloud. smol cloud has no GPU machines. GPU work, including the Vulkan path, runs on smolvm on your own host.
- Skipping host driver setup. The paravirtualized device depends on the host Vulkan stack. If the guest reports no devices, fix the host driver first.
- Sharing a
.smolmachineacross architectures. The artifact runs only on a host with the same architecture (arm64 or x86_64). Build per-architecture artifacts if your team is mixed.
Frequently Asked Questions
Does the guest get a real GPU or a virtual one? A virtual one. smolvm exposes a paravirtualized GPU (virtio-gpu/Venus) to the guest for Vulkan. The physical GPU stays on the host, and no hardware is passed through to any guest.
Why not just pass my GPU through to the VM? Passthrough pins physical hardware to a single guest, needs IOMMU configuration, and blocks live forking. The paravirtualized path lets many machines share one GPU and keeps sub-second cold starts and copy-on-write forks working.
Can I run this on smol cloud? No. smol cloud has no GPU machines. Vulkan and CUDA workloads run on smolvm on your own host; the cloud service is for CPU workloads.
Does this work on Windows? smolvm runs on Windows via Windows Hypervisor Platform, but the Vulkan path is currently unavailable on native Windows. Run Vulkan workloads on a macOS or Linux host.
Conclusion
Paravirtualized Vulkan is the practical route for graphics inside local microVMs: the guest gets a standard Vulkan device, the host keeps ownership of the hardware, and you keep the properties that make microVMs worth using in the first place, like sub-second starts, live forks, and one GPU shared across many machines. Smolmachines ships this path out of the box in smolvm, alongside CUDA API remoting for NVIDIA compute, so you can pick the right virtualization strategy per workload instead of wiring up passthrough. Install smolvm, declare your machine in a Smolfile, enable the paravirtualized GPU, and start rendering. Head to smolmachines.com to get started.