Environment Variables
Last updated
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