Environment Variables
This page lists every environment variable QemuRun-pve reads, its default, and what actually happens when it is unset.
At startup godotenv loads .env from the working directory; when the file is missing the server only logs a warning and reads the process environment. Startup checks only PORT and GATEWAY; every other variable is read when first used.
Required
| Variable | Example | Purpose | When unset |
|---|---|---|---|
PORT |
8080 |
API listen port; also part of the init script URL | Startup fails |
GATEWAY |
192.168.0.1 |
VM gateway; its first three octets form the VM IP prefix | Startup fails |
MAIN_NODE |
pve1 |
Name of the node hosting the service | No VM operation can resolve where to run; SSH initialization cannot build the script URL |
NODE_<name> |
NODE_pve2=192.168.0.12 |
Management IP of every node, main node included | VMs on that node cannot be controlled |
ALLOW_IPS |
192.168.0.10,192.168.0.20 |
Comma-separated client IPs allowed to call mutating endpoints; 0.0.0.0 allows all |
An empty string splits into [""], so every mutating call is denied |
ASSIGN_STORAGE |
local-zfs |
Storage pool for imported disks and cloud-init | Install fails at "checking storage pool" |
Optional
| Variable | Default | Purpose |
|---|---|---|
ASSIGN_IP_START |
100 |
Lower bound for auto-assigned VMIDs; 0 or below 100 becomes 100 |
ASSIGN_IP_END |
254 |
Upper bound for auto-assigned VMIDs; 0 or above 254 becomes 254; swapped automatically when reversed |
VM_MAX_CPU |
unlimited | vCPU cap at install time; larger requests are clamped |
VM_MAX_RAM |
unlimited | Memory cap at install time (MB) |
VM_MAX_DISK |
unlimited | Disk cap at install time (GB); values at or above it become the cap |
VM_BALLOON_MIN |
disabled | Balloon reserve (MB); see the rule below |
VM_ROOT_PASSWORD |
script default | Root password passed to the OS init script; when empty the script falls back to 0123456789 |
Numeric variables that fail to parse as integers are treated as unset.
Ballooning Rule
When VM_BALLOON_MIN is set, memory that meets one of these conditions also gets --numa 1 and --balloon:
| Memory (MB) | --balloon value |
|---|---|
| ≥ 65536 | 49152 |
≥ VM_BALLOON_MIN + 1024 |
memory − VM_BALLOON_MIN |
| otherwise | not set |
Install and /set/memory share this rule.
.env Example
PORT=8080
MAIN_NODE=pve1
GATEWAY=192.168.0.1
ALLOW_IPS=192.168.0.10,192.168.0.20
NODE_pve1=192.168.0.11
NODE_pve2=192.168.0.12
NODE_pve3=192.168.0.13
ASSIGN_IP_START=100
ASSIGN_IP_END=254
ASSIGN_STORAGE=local-zfs
VM_MAX_CPU=32
VM_MAX_DISK=64
VM_MAX_RAM=32768
VM_BALLOON_MIN=2048
VM_ROOT_PASSWORD=
Other files in the working directory are covered in State Files.