# Getting Started

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

## Prerequisites

| Item | Requirement |
|---|---|
| Host | The **main node** of a Proxmox VE cluster, running as `root` (needs `qm`, `pvesh`, `pvesm`, and read access to `/etc/pve/nodes`) |
| Go | 1.25 or higher (`go.mod`), only when building from source |
| Inter-node SSH | Passwordless 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 pool | Active, of type `dir` / `zfspool` / `lvmthin` / `nfs`, able to hold a `cloudinit` disk |
| Outbound access | The 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.

```bash
git clone https://github.com/pardnchiu/QemuRun-pve.git
cd QemuRun-pve
cp .env.example .env
touch .go_qemu_disabled
go build -o QemuRun-pve ./cmd/api
./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](/configuration) 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](/state-files).

## Verify the Service

```bash
curl http://192.168.0.11:8080/api/health
# ok

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.

```bash
curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  -H "Content-Type: application/json" \
  -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`:

```text
data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}

data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}

data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: debian"}

event: close
data: {}
```

Log in with the main node's SSH key:

```bash
ssh debian@192.168.0.120
```

## Next Steps

- Run it as a service or from a release binary: [Deployment](/deployment)
- What each stage does: [Provisioning Pipeline](/provisioning-pipeline)
- Every request field: [Install Endpoint](/api-install)