Go bindings for libkrun, a dynamic library for creating lightweight microVMs using KVM (Linux) or HVF (macOS/ARM64).

go get github.com/mishushakov/libkrun-go/krun

libkrun must be installed on your system. The bundled header in libkrun/include/libkrun.h is used at build time when the submodule is present. Otherwise, pkg-config is used to locate headers and the shared library (libkrun.so or libkrun.dylib), and you can override paths with CGO_CFLAGS/CGO_LDFLAGS.

cd libkrun
make
sudo make install

Install libkrun via Homebrew (repo here):

If you prefer, you can also build and install libkrun from source.

brew tap slp/krun
brew install libkrun pkg-config

pkg-config is used on macOS to locate libkrun headers and libraries from Homebrew. If you installed libkrun via Homebrew, make sure pkg-config can find libkrun.pc (Homebrew usually handles this automatically). If not, set:

export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"

On macOS, binaries include an rpath to /opt/homebrew/lib so Homebrew installs work out of the box. If the runtime loader still cannot find the installed libraries, set a library search path before running your binary:

export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"

package main

import (
	"fmt"
	"os"

	"github.com/mishushakov/libkrun-go/krun"
)

func main() {
	// Create a new VM configuration context.
	ctx, err := krun.CreateContext()
	if err != nil {
		fmt.Fprintf(os.Stderr, "error: %v\n", err)
		os.Exit(1)
	}

	// Configure 2 vCPUs and 512 MiB of RAM.
	ctx.SetVMConfig(krun.VMConfig{NumVCPUs: 2, RAMMiB: 512})

	// Use a host directory as the root filesystem.
	ctx.SetRoot("/path/to/rootfs")

	// Set the command to run inside the VM.
	ctx.SetExec(krun.ExecConfig{
		Path: "/bin/uname",
		Args: []string{"/bin/uname", "-a"},
	})

	// Start the VM. Does not return on success.
	if err := ctx.StartEnter(); err != nil {
		fmt.Fprintf(os.Stderr, "error: %v\n", err)
		os.Exit(1)
	}
}

Some libkrun features are optional and gated behind Go build tags. Without the corresponding tag, calls to those functions return syscall.ENOSYS.

Build with tags:

go build -tags "krun_blk,krun_net" ./...

The typical workflow is:

1. Create a context with krun.CreateContext()
2. Configure the VM using methods on *krun.Context
3. Call ctx.StartEnter() to launch the microVM

Errors are returned as *krun.Error which wraps a syscall.Errno, so you can use errors.Is:

if errors.Is(err, syscall.EINVAL) {
	// handle invalid argument
}

See the examples/ directory:

• features — Query library capabilities (no rootfs needed)
• basic — Run a command in a microVM using a host directory
• vm-with-disk — Boot from a disk image with a custom kernel

Apache 2.0 — see LICENSE for details.