Architecture

This page describes how go-pve-qemu separates HTTP handling from Proxmox VE operations.

System overview

graph LR
    Client[HTTP client] -->|HTTP / SSE| Handler
    Handler --> Service
    Service -->|qm / pvesh| MainNode[Main Proxmox node]
    Service -->|SSH + qm| RemoteNode[Remote Proxmox node]
    Service --> Cloud[Cloud image repository]
    MainNode --> VM[Virtual machine]

Layers

Layer	Responsibility
`cmd/api`	Loads environment settings, initializes Gin, and starts the server.
`internal/config`	Registers `/api` routes and configures CORS handling.
`internal/handler`	Parses requests, validates identifiers, and returns HTTP or SSE responses.
`internal/service`	Runs lifecycle workflows, Proxmox commands, image management, and SSH dispatch.
`internal/model`	Defines request, response, VM, node, and SSE data structures.
`internal/util`	Reads cluster inventory and provides shared validation helpers.

Request path

A client sends a request to a Gin route under /api.
A Handler parses path or JSON parameters and invokes the corresponding Service method.
The Service resolves where the target VM runs and chooses local qm execution or an SSH-dispatched command.
The service returns a regular response, or writes incremental progress as Server-Sent Events.

Cluster execution

The main node executes Proxmox tools locally. For a VM located on another node, the Service builds an SSH command to run qm remotely. This keeps the REST API independent of the cluster topology.

Provisioning workflow

The installation workflow allocates an ID and IP, validates resource limits, resolves or downloads an OS cloud image, creates the VM, imports its disk, applies cloud-init settings, starts it, waits for SSH, initializes the guest, and reboots it. Optional target-node migration occurs after initial VM configuration.

For behavioral details, see Core Concepts and API Reference.