Skip to main content
Run a microVM inside a Kubernetes pod, share a file with it, and read back the result.
This example uses a privileged container with broad node access. Use a dedicated test node, and run untrusted code only inside the microVM.

Prerequisites

  • A Linux worker with usable /dev/kvm. Virtual workers need nested virtualization.
  • Permission to run privileged pods and mount host devices.
  • Docker, kubectl access, and an image registry the worker can pull from.
  • Pod network access to download the guest image.
On the worker, check that KVM is available:
For local Kubernetes clusters, the Linux VM must expose KVM. macOS hypervisor support alone is not enough.

Build the image

Save these two files in an empty directory. This complete application uses Python and asks a sandbox to uppercase a shared file. The same bind-mount workflow is available in TypeScript, Rust, and Go; Ruby does not expose mount configuration.
Create agent.py:
Volume.bind() shares /workspace from the application container with the guest.Add Dockerfile:
The Python package includes the runtime and kernel firmware; the pod needs no Docker daemon.
Replace REGISTRY/PROJECT here and in the manifest, then build and push:
For x86-64 workers, use --platform linux/amd64 and amd64 in the manifest below. For private images, configure Kubernetes imagePullSecrets for the application image and microsandbox registry credentials for the guest image.

Run the pod

Replace YOUR_KVM_NODE with your worker name, then create a test namespace:
The label selects the worker; it does not enable KVM. The namespace must allow privileged pods and host device mounts. Save pod.yaml with your image reference:
The pod mounts the worker’s KVM device and uses temporary volumes for runtime data and shared files. Apply and wait for completion:
The first image download may take longer than five minutes. If the pod fails, the wait command still waits for its timeout; press Ctrl-C and check troubleshooting. Expected output:
The application prints the guest’s output after removing the sandbox, then the pod completes. To rerun, delete the pod and reapply the manifest.

Clean up

Delete the test namespace and remove the worker label:
Remove the label only if you added it and no other workloads use it.

Troubleshooting

To run a diagnostic instead of the application, add this under the agent container in pod.yaml:
Recreate the pod, wait for completion, and read the results:
Check the KVM device and access results. Remove command and recreate the pod to run the application again.

Beyond the example

  • Storage: emptyDir survives container restarts but is deleted with the pod. Use a PVC for durable files. Keep /msb private to each pod; persisting it does not keep VMs running.
  • Resources: allow memory and disk space for the application, guests, and runtime. This example gives a 512 MiB guest a 2 GiB pod limit. Keep runtime volumes disk-backed.
  • Shutdown: the context manager kills and removes the sandbox. For graceful shutdown, call await sandbox.stop() first. Long-running applications also need a SIGTERM handler to stop work and shut down sandboxes within the pod’s grace period.

Device plugins

A KVM device plugin can provide device access without a privileged application container. A host mount alone may not grant that access. Request the plugin’s resource in the container limits, remove the kvm volume and mount, and remove privileged: true. Resource names such as devices.kubevirt.io/kvm depend on the plugin. Verify microVM boot with your device permissions and seccomp/AppArmor/SELinux policies before using this setup. The plugin may itself require privileges. A KVM allocation does not limit VM count; control concurrency in your application.

Validation status

Tested end to end on an x86-64 K3s worker in Google Cloud: microVM boot, shared files, diagnostics, and cleanup across repeated runs. ARM64 Kubernetes execution and device-plugin configurations remain unverified.