Getting Started

Install and operate the go-pve-qemu REST service on a Proxmox VE main node.

Prerequisites

Requirement	Purpose
Go 1.20 or later	Build the API server
Proxmox CLI	`qm`, `pvesh`, and `pvesm` execute VM and storage operations
SSH keys	Main-node access to remote cluster nodes without interactive prompts
Active storage	The storage named by `ASSIGN_STORAGE` must be available

Build and run

git clone https://github.com/pardnchiu/go-pve-qemu.git
cd go-pve-qemu
cp .env.example .env
# configure the required environment variables
go build -o go-pve-qemu ./cmd/api
./go-pve-qemu

The process loads .env when available, requires PORT and GATEWAY, registers the Gin routes, and listens on the configured port.

Verify the service

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

Provision a VM

curl -N -X POST http://localhost:8080/api/vm/install \
  -H 'Content-Type: application/json' \
  -d '{"os":"ubuntu","version":"22.04","name":"web-01","cpu":2,"ram":4096,"disk":"40G"}'

The -N option lets curl print each SSE event immediately. See Configuration before provisioning and API Reference for all fields.