microvm

README

weft-microvm

Host-side runtime library for microVMs — the Docker-style path where an OCI image is pulled, its rootfs extracted, and booted as a lightweight VM sharing a common weft-microvm-init kernel over virtio-fs. This is the runtime behind the weft microvm CLI; it is not the classic full-VM path (boot.iso + cloud-init).

Extracted from the former standalone weft-microvm runner (weft-microvm) so the logic lives in the openweft org and is consumed directly by the single weft binary — there is no separate weft-microvm binary anymore.

Module

github.com/openweft/weft-microvm

Model (Docker-like, not classic VM)

• Pull an OCI image → rootfs extracted to $XDG_DATA_HOME/weft-microvm/images/<refsafe>/rootfs/, with .weft-microvm/config.json materialised from the image config.
• Run boots a microVM by dialing the weft agent's gRPC API and calling RegisterMicroVM: the rootfs is shared into the guest over virtio-fs (mount tag rootfs0); the kernel/init is the shared weft-microvm-init UKI, not a per-VM boot ISO; no per-VM cloud-init seed.
• Lifecycle verbs (list / rm / logs) are thin gRPC clients and live in the weft microvm cobra command, not in this library.

API

// Run prepares the rootfs and registers+starts the microVM via the weft agent.
// Dispatches to the pod path when Args.Pod != "".
func Run(args Args) error

// RunPod boots a multi-container pod manifest (weft-init as PID 1).
func RunPod(args Args) error

// Pull caches an OCI image: pull + extract rootfs + write .weft-microvm/config.json.
func Pull(image string) error

type Args struct {
	Image     string   // OCI ref, e.g. "alpine:3.21"
	Cmd       []string // entrypoint override (the `-- CMD…` tail)
	Detach    bool
	MountTag  string   // virtio-fs tag (default "rootfs0")
	WeftSocket string   // weft agent gRPC socket (default ~/.weft/weft.sock)
	Project   string   // tenant project namespace
	Pod       string   // path to a pod manifest JSON (pod mode)
}

Sub-package initbuild:

// PackToFile packs a Linux weft-microvm-init ELF into an initramfs cpio.gz.
func PackToFile(initBinary, dst string) error

Used by

• openweft/weft cmd/weft/microvm — the weft microvm command group (run / pull / ls / rm / logs / init-build).

Related

• openweft/weft-microvm-init — guest-side weft-microvm-init / pod supervisor.
• cloud-boot/init — pkg/oci (OCI pull) + pkg/cpio (initramfs).
• openweft/weft-proto — RegisterMicroVM gRPC contract.

Documentation

Index

• func KernelPath() string
• func Pull(image string) error
• func PullKernel(image string) error
• func Run(args Args) error
• func RunPod(a Args) error
• type Args
• type PreparedBoot
  • func Prepare(image string) (*PreparedBoot, error)

Functions

func KernelPath

func KernelPath() string

KernelPath is the on-disk location of the shared microVM kernel binary — $XDG_DATA_HOME/weft-microvm/kernel — written by PullKernel and read by the agent's RegisterMicroVM. Exported because the agent reads it via the same path resolution rule the puller uses.

func Pull

func Pull(image string) error

Pull resolves `image`, downloads everything, and materialises the rootfs + .weft-microvm/config.json. Returns nil on success.

func PullKernel

func PullKernel(image string) error

PullKernel resolves the OCI artifact reference, downloads the kernel layer, and atomically replaces $XDG_DATA_HOME/weft-microvm/kernel. Re-running with the same ref is a (cheap) re-download — content-addressable dedup is left to the underlying transport; here we just always overwrite.

func Run

func Run(args Args) error

Run is the typed entry point: dispatch to pod mode (multi- container, weft-init PID 1) when Args.Pod is set, otherwise the single-container microVM path.

func RunPod

func RunPod(a Args) error

RunPod expands the manifest at Args.Pod, builds the weft pod.Spec + virtio-fs shares, writes pod.json into a config share, and registers/starts the micro-VM with weft-init as PID 1. It is the pod-mode branch dispatched from Run.

Types

type Args

type Args struct {
	// Image is the OCI reference to boot (e.g. "alpine:3.21" or
	// "ghcr.io/example/app:v1.2.3"). Required in single-container
	// mode (i.e. when Pod is empty).
	Image string

	// Cmd overrides the image's entrypoint+cmd when non-nil
	// (equivalent to the `-- CMD…` tail in a CLI front-end, e.g.
	// Cmd=["sh","-c","echo hi"]).
	Cmd []string

	// Detach, when true, returns once the VM is alive rather than
	// streaming stdio until exit. Not implemented yet.
	Detach bool

	// MountTag is the virtio-fs tag exposed inside the guest.
	// Default "rootfs0"; rarely changed but useful for parallel
	// runs sharing the same kernel.
	MountTag string

	// WeftSocket overrides the path to weft's Unix gRPC socket.
	// Empty means use the default ~/.weft/weft.sock (same as weft).
	WeftSocket string

	// Project is the multitenant namespace the new microVM lands
	// in. Empty resolves to weft's default project (currently
	// `usr-<weft-os-user>`); a string like `team-net` lands the VM
	// in a shared project. Phase-2 auth will gate access here.
	Project string

	// Pod, when non-empty, is the path to a pod manifest JSON
	// (multi-container mode). Mutually exclusive with Image and
	// Cmd: the manifest names its own images and commands. Pod mode
	// boots weft-init (a supervisor PID 1) instead of weft-microvm-init.
	Pod string
}

Args holds the typed inputs for Run. The CLI front-end populates it from parsed flags/positionals; library callers build it directly.

type PreparedBoot

type PreparedBoot struct {
	// Name is the conventional "weft-microvm-<refsafe>". Callers that
	// already have a name on the request override this ; callers that
	// don't (eg. weft-network's lifecycle.Ensure passing the Router
	// uuid) plug it in directly.
	Name string

	// Kernel + Initrd : populated in direct-Linux mode (the default
	// produced by the weft-microvm-init kernel + ncl-init initrd in
	// the local cache). Mutually exclusive with BootISO.
	Kernel string
	Initrd string

	// BootISO : populated only in UKI mode (when locateBootArtefacts
	// finds a boot.iso but no separate kernel).
	BootISO string

	// Cmdline synthesised for the weft-microvm-init guest. Carries
	// the rootfs share tag so the guest knows which virtio-fs share
	// to pivot-root into : "weft.rootfs=virtiofs:<tag> console=hvc0".
	Cmdline string

	// SharePath is the host-side path to the extracted OCI rootfs
	// (post-Pull). ShareTag is the virtio-fs / 9p tag the guest
	// mounts at boot — default "rootfs0".
	SharePath string
	ShareTag  string
}

PreparedBoot is the bundle a `weft RegisterMicroVM` consumer (typically the weft daemon's server-side handler) plugs into the boot + shares fields after resolving an OCI image.

Mirrors what runMicroVM assembles client-side ; the goal of Prepare is to expose that same translation to any in-process caller — so the gRPC RegisterMicroVM handler can accept a bare `image` field and do the OCI pull + share assembly server-side without forcing every client (Go, Python, Terraform) to re-implement the dance.

func Prepare

func Prepare(image string) (*PreparedBoot, error)

Prepare resolves an OCI image into the artefacts RegisterMicroVM needs. Pure host-side prep — doesn't dial weft, doesn't register anything ; the caller does that with the returned PreparedBoot.

Lifecycle :

1. Compute the cache path for the image's rootfs.
2. If missing on disk, Pull() it (matches `docker run`'s auto-pull UX). Honors WEFT_NO_AUTO_PULL=1 for strict offline mode.
3. Locate the boot artefacts (the shared weft-microvm-init kernel + initrd cached under $XDG_DATA_HOME/weft-microvm/, or the fallback UKI boot.iso).
4. Synthesise the cmdline + share tag.

Returns InvalidArgument when image is empty.