repository·main·Indexed 43 days ago
https://github.com/libkrun/krunkitA CLI tool for launching configurable virtual machines using the libkrun platform, optimized for macOS 14 or newer. Version 1.3.2 supports resource allocation (vCPUs and RAM up to 60 GiB), EFI bootloaders, and various virtio devices including virtio-blk, virtio-net, virtio-fs, and virtio-vsock. It includes a RESTful service API for managing VM state and supports nested virtualization on M3 or newer CPUs with macOS 15+.
To install krunkit and its dependencies (including libkrun) using Homebrew, tap the slp/krun repository and install the package.
Note: krunkit is only supported on hosts running macOS 14 or newer.
brew tap slp/krun
brew install krunkitEnsure libkrun is installed on your system before building.
To build and install using the default prefix (/usr/local):
make
sudo make installIf you are using libkrun installed via Homebrew or MacPorts, specify the appropriate PREFIX (e.g., /opt/homebrew for Apple Silicon Homebrew):
make PREFIX=/opt/homebrew
sudo make install PREFIX=/opt/homebrewWhen configuring a KrunContext, there are specific constraints on resource allocation:
If these limits are exceeded, KrunContext::try_from will return an error.
If you previously installed krunkit using the deprecated slp/krunkit tap, you must remove all packages from that tap and then untap it before upgrading to the new version via slp/krun.
brew list --full-name | grep "^slp/krunkit/" | xargs brew uninstall
brew untap slp/krunkitThe RESTful service (defaulting to tcp://localhost:8081) allows managing the virtual machine state.
GET /vm/state
Response: VirtualMachineState{Running, Stopped}
POST /vm/state
Body:
{ "state": "Stop" }Response: VirtualMachineStateStopped
curl -X POST http://localhost:8081/vm/state -d '{"state": "Stop"}'Specify the hardware resources available to the virtual machine using --cpus and --memory.
--cpus: Number of vCPUs.--memory: Amount of RAM in MiB (mebibytes).--nested: Enable Nested Virtualization. Requirement: M3 or newer CPU and macOS 15+.Example for 2 vCPUs and 2048 MiB RAM:
--cpus 2 --memory 2048--cpus 2 --memory 2048 --nestedAdd a disk to the virtual machine using the virtio-blk device type via the --device flag.
virtio-blk device specified becomes the root disk (/dev/vda).virtio-blk devices become data disks (/dev/vdb, /dev/vdc, etc.).Arguments:
path: Path to the disk image file.format: Disk image format (raw or qcow2).Example:
--device virtio-blk,path=/Users/user/disk-image.raw,format=raw--device virtio-blk,path=/Users/user/disk-image.raw,format=rawShare a host directory with the guest using virtio-fs. The guest can mount this directory using: mount -t virtiofs <MOUNT_TAG> <MOUNT_POINT>.
Arguments:
sharedDir: Path to the host directory.mountTag: The tag used for mounting in the guest.permissionSemantics: (Optional) complete or simplified. Default is simplified.Example:
--device virtio-fs,sharedDir=/Users/user/shared-dir,mountTag=MOUNT_TAG--device virtio-fs,sharedDir=/Users/user/shared-dir,mountTag=MOUNT_TAGAdd a virtio-vsock communication channel. Since macOS lacks native AF_VSOCK support, krunkit uses a UNIX socket proxy on the host.
Arguments:
port: The AF_VSOCK port to connect to on the guest.socketURL: The path to the UNIX socket on the host.listen: (Default) Enables guest-to-host communication.connect: Enables host-to-guest communication.Example (Guest-to-Host):
--device virtio-vsock,port=1024,socketURL=/Users/user/vm-socket.sockExample (Host-initiated/Connect mode):
--device virtio-vsock,port=1024,socketURL=/Users/user/vm-socket.sock,connect--device virtio-vsock,port=1024,socketURL=/Users/user/vm-socket.sockUse the following flags to configure logging, the RESTful service, and process management for krunkit:
--krun-log-level: Set libkrun log level. Values: 0=off, 1=error, 2=warn, 3=info (default), 4=debug, 5 or more=trace.--log-file: Path to write logs. Appends to existing files.--restful-uri: URI for the RESTful service. Schemes: tcp, none, or unix. none disables the service. Defaults to none://.--pidfile: Path to write the process ID.--timesync: Specify a Vsock port for host-to-guest time synchronization via qemu-guest-agent.Example for time synchronization:
--timesync vsockPort=1234On the guest, run:
/usr/bin/qemu-ga --method=vsock-listen --path=3:1234 --logfile=/var/log/qemu-ga.log -v--krun-log-level 4 --log-file /tmp/krunkit.log --restful-uri tcp://localhost:8081Add a network interface using the virtio-net device type via the --device flag.
type=unixgram: Uses a UNIX datagram socket backend (e.g., gvproxy or vmnet-helper).type=unixstream: Uses a UNIX stream socket backend (e.g., passt or socket_vmnet).mac: MAC address of the VM.path: Path to the UNIX socket (mutually exclusive with fd).fd: UNIX socket file descriptor (mutually exclusive with path).offloading: (Optional) Enable network offloading. Default is off.vfkitMagic: (Optional) Send the vfkit magic value after connection. Only supported with type=unixgram. Default is off.Using vmnet-helper (basic):
--device virtio-net,type=unixgram,path=/Users/user/vm-network.sock,mac=ff:ff:ff:ff:ff:ffUsing gvproxy with offloading and vfkit magic:
--device virtio-net,type=unixgram,path=/Users/user/vm-network.sock,mac=ff:ff:ff:ff:ff:ff,offloading=on,vfkitMagic=onUsing passt (unixstream):
--device virtio-net,type=unixstream,fd=<passt_fd>,mac=ff:ff:ff:ff:ff:ff,offloading=true--device virtio-net,type=unixgram,path=/Users/user/vm-network.sock,mac=ff:ff:ff:ff:ff:ff,offloading=on,vfkitMagic=onRedirect virtual machine text output to a file using the virtio-serial device.
Arguments:
logFilePath: Path to the file where serial output will be written.Example:
--device virtio-serial,logFilePath=/Users/user/vm-output.log--device virtio-serial,logFilePath=/Users/user/vm-output.log