NAME

puter-quickstart - getting started with puter

DESCRIPTION

This guide walks through installing puter and booting your first VM.

PREREQUISITES

The following packages are required to build and run puter:

Go 1.25+: Required to build puter from source.
cloud-hypervisor: The VM hypervisor. Must have CAP_NET_ADMIN capability set.
qemu-img: Disk image creation and conversion. Package name is qemu-img on Arch or qemu-utils on Debian/Ubuntu.
fakeroot: Preserves file ownership when creating disk images without root. Package name is base-devel on Arch or fakeroot on Debian/Ubuntu.
e2fsprogs: Provides mkfs.ext4(8) for creating populated ext4 filesystems.

INSTALL

Clone the repository and build:

$ git clone https://git.sr.ht/~a73x/puter
$ cd puter
$ make build

This produces two binaries in bin/: puter (unprivileged CLI) and puterd (privileged daemon).

Set the required Linux capabilities on the daemon binary:

$ make caps

This runs sudo setcap cap_net_admin,cap_net_raw,cap_net_bind_service+ep on the puterd binary.

SETUP

Initialize puter by downloading the kernel and initrd:

$ puter init

Start the daemon in another terminal (or as a systemd service):

$ puterd

FIRST VM

Boot your first VM:

$ puter start myvm

This pulls an OCI base image (on first run), creates a qcow2 overlay, requests a TAP device from the daemon, launches cloud-hypervisor, and configures networking via the guest agent.

SSH into the running VM:

$ puter ssh myvm
root@myvm:~#

List running VMs:

$ puter list
NAME   NODE   STATUS   IP
myvm   local  running  10.0.0.10

Stop the VM:

$ puter stop myvm

Delete the VM (removes state and overlay):

$ puter delete myvm