# 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`](/api-resources) share this rule.

## `.env` Example

```bash
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](/state-files).