v0.1.7

Getting Started

Last updated


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

Prerequisites


ItemRequirement
HostThe main node of a Proxmox VE cluster, running as root (needs qm, pvesh, pvesm, and read access to /etc/pve/nodes)
Go1.25 or higher (go.mod), only when building from source
Inter-node SSHPasswordless 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 poolActive, of type dir / zfspool / lvmthin / nfs, able to hold a cloudinit disk
Outbound accessThe 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.
  1. git clone https://github.com/pardnchiu/QemuRun-pve.git
  2. cd QemuRun-pve
  3. cp .env.example .env
  4. touch .go_qemu_disabled
  5. go build -o QemuRun-pve ./cmd/api
  6. ./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


  1. curl http://192.168.0.11:8080/api/health
  2. # ok
  3. 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.
  1. curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  2. -H "Content-Type: application/json" \
  3. -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:
  1. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}
  2. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}
  3. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: debian"}
  4. event: close
  5. data: {}

Log in with the main node's SSH key:
  1. ssh debian@192.168.0.120

Next Steps


中文