Documentation v0.1.7
Home GitHub

Getting Started

This page walks through building QemuRun-pve on a Proxmox VE main node and creating a first VM with a single API call.

Prerequisites

Item Requirement
Host The main node of a Proxmox VE cluster, running as root (needs qm, pvesh, pvesm, and read access to /etc/pve/nodes)
Go 1.25 or higher (go.mod), only when building from source
Inter-node SSH Passwordless key-based root SSH from the main node to every other node
Subnet /24, where each VM's last IP octet equals its VMID, so VMIDs must fall within 100–254
Storage pool Active, of type dir / zfspool / lvmthin / nfs, able to hold a cloudinit disk
Outbound access The main node can download the official Debian, Rocky Linux, and Ubuntu cloud images

Build and Run

The service resolves .env, sh/, and the .go_qemu_* state files relative to its working directory, so run it inside the cloned repository.

git clone https://github.com/pardnchiu/QemuRun-pve.git
cd QemuRun-pve
cp .env.example .env
touch .go_qemu_disabled
go build -o QemuRun-pve ./cmd/api
./QemuRun-pve

On startup the server prints every registered route, then goQemu run at localhost:<PORT>. It exits immediately when PORT or GATEWAY is unset; see Environment Variables for the rest.

.go_qemu_disabled must exist even when empty; without it the VM list and every state-checked endpoint fail. See State Files.

Verify the Service

curl http://192.168.0.11:8080/api/health
# ok

curl http://192.168.0.11:8080/api/vm/list

Create Your First VM

-N disables curl buffering so SSE progress shows up live. Omitting id auto-assigns both VMID and IP.

curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  -H "Content-Type: application/json" \
  -d '{"os": "debian", "version": "12", "cpu": 2, "ram": 4096, "disk": "32G"}'

The stream ends by listing the VMID, IP, and login user, followed by event: close:

data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}

data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}

data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: debian"}

event: close
data: {}

Log in with the main node's SSH key:

ssh debian@192.168.0.120

Next Steps

中文