# krunkit Command Line

`krunkit` can launch configurable virtual machines using macOS's hypervisor framework and the `libkrun` virtual
machine monitor library. The `libkrun` virtual machine configuration can be specified from command line arguments.

Specifying a virtual machine's vCPU and RAM allocation is required. Adding devices is optional, yet most workloads
will require a root disk to be useful.

## Generic Options

- `--krun-log-level`

Set the log level for libkrun. Supported values: 0=off, 1=error, 2=warn, 3=info (default), 4=debug, 5 or more=trace.

- `--restful-uri`

The URI (address) of the RESTful service. If not specified, defaults to `tcp://localhost:8081`. Valid schemes are
`tcp`, `none`, or `unix`. A scheme of `none` disables the RESTful service.
### Virtual Machine Resources

- `--cpus`

Number of vCPUs available to a virtual machine.

- `--memory`

Amount of RAM available to a virtual machine. Value is in MiB (mebibytes, 1024^2 bytes).

- `--nested`

Enable Nested Virtualization.

Note: this requires an M3 or newer CPU and macOS 15+.

#### Example

This configures a virtual machine to use two vCPUs and 2048 MiB of RAM:

```
--cpus 2 --memory 2048
```

## Bootloader Configuration

### EFI bootloader

`--bootloader efi` allows booting a disk image using EFI, which removes the need for providing external kernel/initrd/... jthe disk image bootloader will be started by the EFI firmware, which will in turn know which kernel it should be booting.

#### Arguments
- `variable-store`: path to a file which EFI can use to store its variables
- `create`: indicate whether the `variable-store` file hould be created or not if missing.

> [!NOTE]
> This option is ignored by the commandline. It is added purely for vfkit parity. `krunkit` only supports the EFI bootloader configuration and handles all associated actions without further user configuration.

## Device Configuration

Various virtio devices can be added to a virtual machine. They are all paravirtualized devices that can be
specified using the `--device` flag.

### Disk

The `virtio-blk` option adds a disk to a virtual machine. This disk is backed by an image file on the host
machine. At least one virtio-blk device must be specified on the commandline. The first virtio-blk argument
will be used as a virtual machine's root disk (`/dev/vda`). The subsequent virtio-blk arguments will be used
as a virtual machine's data disk(s) (`/dev/vd[b-z]`).

#### Arguments

- `path`: Path to the disk image file.
- `format`: Format of the disk image. Supported formats: raw, qcow2.

#### Example

This adds a virtio-blk device to a virtual machine which will be backed by an image at
`/Users/user/disk-image.raw`:

```
--device virtio-blk,path=/Users/user/disk-image.raw,format=raw
```

### Networking

The `virtio-net` option adds a network interface to a virtual machine.

#### Arguments

- `unixSocketPath`: Path to a UNIX socket to attach to the guest network interface.
- `mac`: MAC address of a virtual machine.

#### Example

This adds a virtio-net device to a virtual machine and redirects all guest network traffic to the corresponding
socket at `/Users/user/vm-network.sock` with a MAC address of `ff:ff:ff:ff:ff:ff`:

```
--device virtio-net,unixSocketPath=/Users/user/vm-network.sock,mac=ff:ff:ff:ff:ff:ff
```

### Serial Port

The `virtio-serial` option adds a serial device to a virtual machine. This allows for redirection of virtual
machine text output.

#### Arguments

- `logFilePath`: Path to a file in which a virtual machine's serial port output should be written.

#### Example

This adds a virtio-serial device to a virtual machine, and will redirect the virtual machine's text output to
`/Users/user/vm-output.log`:

```
--device virtio-serial,logFilePath=/Users/user/vm-output.log
```

### vsock

The `virtio-vsock` option adds a vsock communication channel between the host and guest. macOS does not have host
support for `AF_VSOCK` sockets, so the virtual machine monitor will maintain a vsock-UNIX socket proxy to
facilitate communication between the two.

Multiple instances of a `virtio-vsock` device can be specified, yet port numbers for these sockets must be unique.

#### Arguments

- `port`: `AF_VSOCK` port to connect to on the guest.
- `socketURL`: Path to the UNIX socket on the host.

#### Example

This adds a virtio-vsock device to a virtual machine, and will forward all guest socket communication to
`/Users/user/vm-socket.sock` (a virtual machine can connect to the vsock on port `1024`):

```
--device virtio-vsock,port=1024,socketURL=/Users/user/vm-socket.sock
```

### File Sharing

The `virtio-fs` option allows a guest to share a file system directory with a host. The directory can be mounted
in the guest with `mount -t virtiofs MOUNT_TAG /mnt`, with `MOUNT_TAG` corresponding to the mount tag specified in
the arguments.

#### Arguments

- `sharedDir`: Path to the host directory that will be shared with the guest.
- `mountTag`: Tag to be used to mount the shared directory in the guest.

#### Example

This will share `/Users/user/shared-dir` with the guest:

```
--device virtio-fs,sharedDir=/Users/user/shared-dir,mountTag=MOUNT_TAG
```

## Restful Service

Recall that the RESTful service is started at the address specified in the `--restful-uri` argument (or
`tcp://localhost:8081` if not specified).

### Getting a virtual machine's state

Used to obtain the state of a running virtual machine.

`GET /vm/state`

Response: `VirtualMachineState{Running, Stopped}`

### Stopping a virtual machine

`POST /vm/state` `{ "state": "Stop" }`

Response: `VirtualMachineStateStopped`