go-proxmox

Proxmox API Client Go Package

Join the community to discuss ongoing client development usage, the proxmox API or tooling in the #go-proxmox channel on the Gophers Slack and see the self generated docs for more usage details.

A go client for Proxmox VE. The client implements /api2/json and inspiration was drawn from the existing Telmate package but looking to improve in the following ways...

• Treated as a proper standalone go package
• Types and JSON marshal/unmarshalling for all end points
• Full Testing, unit testing with mocks and integration tests against an API endpoint
• Configuration options when creating a client for flexible usage
• Client logging for debugging within your code
• Context support
• Added functionality for better go tooling built on this library, some things we'd like
  • Boot VM from qcow URL, inspiration: Proxmox Linux Templates
  • Dynamic host targeting for VM, Proxmox lacks a scheduler when given VM params it will try and locate a host with resources to put it
  • cloud-init support via no-cloud ISOs uploaded to node data stores and auto-mounted before boot, inspiration quiso
  • Unattended XML Support via ISOs similar to cloud-init ideas
  • node/vm/container shell command support via KVM proxy already built into proxmox

API coverage

go-proxmox wraps 100% of the upstream PVE /api2/json surface for PVE 8.x and 9.x — every endpoint in the API viewer has a typed Go wrapper, with three intentional exceptions documented in mage/endpoints/endpoints.go: the two mtunnelwebsocket URL builders (the library returns the signed URL via MigrationTunnelWebSocketPath; the caller plumbs into their own websocket dialer) and the file-restore/download streaming binary endpoint.

Coverage is tracked in CI via mage endpoints:coverage, which diffs the live PVE schema against the package's call sites. Run it locally to confirm a fresh schema bump didn't add anything new:

mage endpoints:sync       # refresh .cache/pve-api/endpoints.json from upstream
mage endpoints:coverage   # print per-area coverage; lists any missing endpoints

Core developers are home lab enthusiasts working in the virtualization and kubernetes space. The common use case we have for Proxmox is dev stress testing and validation of functionality in the products we work on, we plan to build the following tooling around this library to make that easier.

• Docker Machine Driver for consumption by Rancher
• Terminal UI inspired by k9s for quick management of PVE Clusters
• Terraform Provider with better local-exec and cloud-init/unattend xml support
• Cluster API Provider Proxmox to create kubernetes clusters

Usage

Create a client and use the public methods to access Proxmox resources.

Basic usage with login with a username and password credential

package main

import (
	"context"
	"fmt"
	
	"github.com/luthermonson/go-proxmox"
)

func main() {
    credentials := proxmox.Credentials{
		Username: "root@pam", 
		Password: "12345",
    }
    client := proxmox.NewClient("https://localhost:8006/api2/json",
		proxmox.WithCredentials(&credentials),
    )
	
    version, err := client.Version(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Println(version.Release) // 7.4
}

Usage with Client Options

Lab setup (self-signed PVE, short timeout, API token):

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/luthermonson/go-proxmox"
)

func main() {
	client := proxmox.NewClient("https://localhost:8006/api2/json",
		proxmox.WithAPIToken("root@pam!mytoken", "somegeneratedapitokenguidefromtheproxmoxui"),
		proxmox.WithInsecureSkipVerify(),     // lab only
		proxmox.WithTimeout(30*time.Second),  // http.DefaultClient has no timeout
	)

	version, err := client.Version(context.Background())
	if err != nil {
		panic(err)
	}
	fmt.Println(version.Release) // 6.3
}

Production setup (pinned CA, mTLS optional):

caBundle, _ := os.ReadFile("/etc/ssl/certs/pve-cluster.pem")
pool := x509.NewCertPool()
pool.AppendCertsFromPEM(caBundle)

client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
	proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
	proxmox.WithRootCAs(pool),
	proxmox.WithTimeout(30*time.Second),
	// optional mTLS:
	// proxmox.WithClientCertificate(clientCert),
)

Credential authentication and 2FA

API tokens are the right choice for daemons and CI. For interactive tools — anything with a human typing a password and a TOTP code — use credentials with WithOTP and WithEagerAuth:

client := proxmox.NewClient(url,
	proxmox.WithCredentials(&proxmox.Credentials{
		Username: "admin",
		Password: password,
	}),
	proxmox.WithDefaultRealm("pam"),  // "admin" gets Realm "pam" merged in
	proxmox.WithOTP("123456"),        // one-shot; consumed on first /access/ticket
	proxmox.WithEagerAuth(),          // see note below
)

WithEagerAuth is worth calling out. PVE's pveproxy enforces a hardcoded 3-second delay on every 401 response as a brute-force mitigation (see PVE::APIServer::AnyEvent's # always delay unauthorized calls by 3 seconds block). With credential auth the library's first request goes out unauthenticated by design — the ticket isn't issued until /access/ticket succeeds — so the first user-facing call eats the full 3 seconds. WithEagerAuth runs CreateSession inside NewClient so that cost is paid once at startup and every subsequent request is a normal ticket-authenticated call. Token auth doesn't trigger the 401 path at all and doesn't need this.

The OTP is consumed exactly once; subsequent RefreshTicket calls renew the session via the ticket itself and don't need a new code. If the session is fully lost later (PVE restart invalidates tickets), construct a fresh client with a fresh OTP — TOTP codes can't be cached.

Resource traversal: instance handles

Most resources identified by an id/name follow a getter-returns-handle pattern. The handle carries the parent's client and identifying fields, so callers don't re-thread (node, id) on every call.

cluster, _ := client.Cluster(ctx)

// SDN controllers — getter on the parent, operations on the instance.
ctrl := cluster.SDNController("evpn-1")
if err := ctrl.Update(ctx, &proxmox.SDNControllerOptions{ASN: proxmox.IntOrBool(65000)}); err != nil {
    panic(err)
}
_, _ = ctrl.Delete(ctx)

// Same pattern for VM/container snapshots, firewall rules, ceph OSDs/pools/mons,
// HA resources, ACME accounts, custom CPU models, fabrics, IPAMs, prefix-lists, etc.

See AGENTS.md (Required: pick the right shape for new endpoints) for the full inventory of instance types.

Acting on a node, VM or container without fetching it first

client.Node and node.VirtualMachine fetch before they return: the node's status, then the VM's status and config. That is three GETs before a vm.Stop. When you already know where the VM lives and only want to act on it, build a ref instead. A ref makes no request until you call a method:

// Fetch: 3 GETs, then the POST. Use it when you're going to read the VM.
node, err := client.Node(ctx, "pve1")
vm, err := node.VirtualMachine(ctx, 100)
fmt.Println(vm.Status, vm.VirtualMachineConfig.Memory)

// Ref: no requests to build it, so Stop is the POST alone.
ref := client.NodeRef("pve1").VirtualMachineRef(100)
task, err := ref.Stop(ctx)

// A ref has only the node and VMID. Ping fills its status and config.
err = ref.Ping(ctx)
fmt.Println(ref.IsRunning())

// LXC is the same.
ct := client.NodeRef("pve1").ContainerRef(101)
task, err = ct.Start(ctx)

Refs return the ordinary *Node, *VirtualMachine and *Container types, so every method is available:

• Actions (Start, Stop, Shutdown, Reboot, Migrate, Config, Clone, snapshots, firewall, agent, ...) need only the node and VMID, and send exactly the one request they always did.
• Config read-modify-write (AddTag, RemoveTag, CloudInit, UnmountCloudInitISO, and the cloud-init ISO cleanup inside VirtualMachine.Delete) fetch the config themselves when the handle doesn't have it, so existing tags are kept rather than overwritten.
• Accessors (IsRunning, IsStopped, IsPaused, IsHibernated, HasTag) take no context and can't fetch. On a ref they report false until Ping has run.

The node and VMID aren't checked when the ref is built; a VM that doesn't exist fails on the first real call. Refresh a node ref with node.Status(ctx). See examples/vm-refs for a runnable version.

Create a VM and build a template

Creating or editing a VM goes through VirtualMachineOption key/value pairs, whose names are the raw qemu parameter names from the PVE API viewer — the same names qm create takes. VirtualMachineConfig is the read side: GET /config unmarshals into it (that's why its fields use tolerant types like StringOrInt — PVE returns the same field as a number or a quoted string depending on version), and the library never sends it to the API. Don't populate it to create a VM.

node, err := client.Node(ctx, "pve1")
if err != nil {
    panic(err)
}

// Ask the cluster for the next free VMID instead of inventing one.
cluster, err := client.Cluster(ctx)
if err != nil {
    panic(err)
}
vmid, err := cluster.NextID(ctx)
if err != nil {
    panic(err)
}

task, err := node.NewVirtualMachine(ctx, vmid,
    proxmox.VirtualMachineOption{Name: "name", Value: "ubuntu-template"},
    proxmox.VirtualMachineOption{Name: "memory", Value: 2048},
    proxmox.VirtualMachineOption{Name: "cores", Value: 2},
    proxmox.VirtualMachineOption{Name: "scsihw", Value: "virtio-scsi-single"},
    proxmox.VirtualMachineOption{Name: "scsi0", Value: "local-lvm:0,import-from=local:import/noble-server-cloudimg-amd64.qcow2"},
    proxmox.VirtualMachineOption{Name: "ide2", Value: "local-lvm:cloudinit"},
    proxmox.VirtualMachineOption{Name: "net0", Value: "virtio,bridge=vmbr0"},
    proxmox.VirtualMachineOption{Name: "boot", Value: "order=scsi0"},
)
if err != nil {
    panic(err)
}
if err := task.Wait(ctx, time.Second, 5*time.Minute); err != nil {
    panic(err)
}

// The create task itself carries the new VMID: task.ID is the UPID's id
// field, which for a qmcreate task is the VMID. Useful when the task is all
// you're holding.
vmid, err = strconv.Atoi(task.ID)
if err != nil {
    panic(err)
}

vm, err := node.VirtualMachine(ctx, vmid)
if err != nil {
    panic(err)
}

// Post-create edits use the same options: Config is an async POST returning
// a *Task, ConfigSync is a synchronous PUT.
if err := vm.ConfigSync(ctx,
    proxmox.VirtualMachineOption{Name: "ciuser", Value: "ubuntu"},
    proxmox.VirtualMachineOption{Name: "ipconfig0", Value: "ip=dhcp"},
    // sshkeys needs PVE's exact urlencoding — see EncodeSSHKeys.
    proxmox.VirtualMachineOption{Name: "sshkeys", Value: proxmox.EncodeSSHKeys(pubkey)},
); err != nil {
    panic(err)
}

task, err = vm.ConvertToTemplate(ctx)
if err != nil {
    panic(err)
}
if err := task.Wait(ctx, time.Second, 2*time.Minute); err != nil {
    panic(err)
}

The full runnable flow — cloud-image download via Storage.DownloadURL, disk import, cloud-init, resize, template, clone — lives in examples/vm-template.

Permission / capability discovery via Subdirs

PVE's directory-index GETs are ACL-filtered: the response only lists the sub-resources the calling token is permitted to read. Use them to probe what an API token can do without try-and-403 against every endpoint:

node, _ := client.Node(ctx, "pve1")
subdirs, _ := node.Subdirs(ctx)         // ["qemu", "lxc", "storage", ...] filtered by ACL
fw, _ := node.FirewallSubdirs(ctx)      // ["rules", "options", "log"] if reachable

cluster, _ := client.Cluster(ctx)
sdnAreas, _ := cluster.SDNSubdirs(ctx)  // ["vnets", "zones", "controllers", ...]

CSV type for comma-joined PVE fields

A few PVE fields serialize as comma-joined strings on the wire (most notably SDNZone.Nodes and .Peers, plus various group/realm fields). proxmox.CSV is a typed []string whose UnmarshalJSON accepts both "a,b,c" and ["a","b","c"], and whose MarshalJSON always emits the comma-joined form PVE expects:

// Read side: PVE returns `"nodes": "pve1,pve2,pve3"`. CSV presents it as a slice.
zone, _ := cluster.SDNZone(ctx, "vxlan-1")
for _, n := range zone.Nodes {                  // proxmox.CSV — iterable like []string
    fmt.Println(n)
}
allNodes := []string(zone.Nodes)                // explicit cast when you need []string

// Write side: the matching *Options types take a plain comma-joined string,
// because PVE only accepts that form on POST/PUT.
_ = cluster.NewSDNZone(ctx, &proxmox.SDNZoneOptions{
    Name:  "vxlan-1",
    Type:  "vxlan",
    Nodes: "pve1,pve2,pve3",
})

Proxies

Route every request through a forward proxy. Works for http://, https://, and socks5:// URLs:

proxyURL, _ := url.Parse("http://proxy.corp.example.com:3128")
client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithProxy(proxyURL),
)

Or use the standard HTTP_PROXY / HTTPS_PROXY / NO_PROXY env-var convention:

client := proxmox.NewClient("https://pve.example.com:8006/api2/json",
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithProxyFromEnvironment(),
)

WithProxyFromEnvironment reads env vars per-request (via Go's standard http.ProxyFromEnvironment), so changes after NewClient take effect on the next call. Composes with WithHTTPClient, the TLS options, retry, and request interceptors — option order doesn't matter.

Retries on transient failures

PVE returns 502 / 503 during cluster transitions and 429 when rate-limited. WithRetry installs a RoundTripper wrapper that retries with full-jitter exponential backoff, honors Retry-After on 429 / 503, and respects request-context cancellation:

client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(),  // defaults: 3 attempts, 200ms–5s backoff
)

Tune the defaults for flakier upstreams:

client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(
        proxmox.WithRetryMax(5),
        proxmox.WithRetryBackoff(500*time.Millisecond, 30*time.Second),
    ),
)

Or replace the predicate that decides what to retry — for example to also retry 423 Locked while a cluster transition is in flight:

retryOn423 := func(res *http.Response, err error) bool {
    if err != nil {
        return true
    }
    switch res.StatusCode {
    case http.StatusLocked, http.StatusBadGateway,
        http.StatusServiceUnavailable, http.StatusGatewayTimeout,
        http.StatusTooManyRequests:
        return true
    }
    return false
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRetry(proxmox.WithRetryCondition(retryOn423)),
)

The default predicate retries network errors plus 502 / 503 / 504 / 429. Only idempotent verbs (GET, PUT, DELETE) and POST with a fully-buffered body are eligible — this client always buffers request bodies as []byte, so POST is rewindable in practice.

Request interceptors

Run a function on every outgoing request after the auth headers are populated and before the request is sent. Useful for tracing, correlation IDs, custom audit headers, request logging:

addCorrelationID := func(req *http.Request) error {
    req.Header.Set("X-Correlation-Id", "build-1234")
    return nil
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRequestInterceptor(addCorrelationID),
)

Multiple interceptors compose — each WithRequestInterceptor call appends to the chain, and they run in registration order. The first non-nil error short-circuits the request (with a request interceptor: prefix so callers can errors.Is against their own sentinels):

tracing := func(req *http.Request) error {
    // pull the active span from req.Context() and inject W3C traceparent.
    req.Header.Set("Traceparent", traceparent.From(req.Context()))
    return nil
}
audit := func(req *http.Request) error {
    log.Info().Str("method", req.Method).Str("path", req.URL.Path).Msg("pve")
    return nil
}
client := proxmox.NewClient(url,
    proxmox.WithAPIToken("automation@pve!ci", "<secret>"),
    proxmox.WithRequestInterceptor(tracing),
    proxmox.WithRequestInterceptor(audit),
)

The chain fires from Req, Upload, and UploadReader. Websocket upgrades (TermWebSocket, VNCWebSocket) are exempt — the dialer doesn't surface a *http.Request the chain could mutate.

Error handling

Every non-2xx response comes back as a *proxmox.APIError carrying the status code, PVE's message, and the per-parameter errors map from the response body:

var apiErr *proxmox.APIError
if errors.As(err, &apiErr) {
    log.Printf("%s %s -> %d: %s %v",
        apiErr.Method, apiErr.Path, apiErr.StatusCode, apiErr.Message, apiErr.Errors)
}

Classify errors with errors.Is or the matching helper rather than matching on err.Error():

Sentinel	Helper	Matches
ErrNotFound	IsNotFound	404, plus the PVE 500/400 messages that mean a resource doesn't exist (Configuration file '...' does not exist, storage 'x' does not exist, no such user, no such job, No such storage., ...)
ErrNotAuthorized	IsNotAuthorized	401 and 403
ErrForbidden	IsForbidden	403 only
ErrBadRequest	IsBadRequest	400, e.g. Parameter verification failed.; details are in APIError.Errors
ErrRateLimited	IsRateLimited	429; APIError.RetryAfter holds the Retry-After hint
ErrNodeUnreachable	IsNodeUnreachable	595 / 596, which pveproxy returns when it can't reach the target cluster node

vm, err := node.VirtualMachine(ctx, 100)
switch {
case proxmox.IsNotFound(err):
    // create it
case proxmox.IsNodeUnreachable(err):
    // try another node
case err != nil:
    return err
}

PVE reports most missing resources as a generic 500 rather than a 404, so ErrNotFound is partly matched on the message. The patterns are deliberately conservative and listed with their upstream sources in errors.go. For anything they don't cover, check APIError.StatusCode and APIError.Message directly.

Error() keeps the text these errors had before APIError existed: it starts with the HTTP status line (500 QEMU guest agent is not running), 400s keep the bad request: <status> - <errors> form, and 401/403 keep the not authorized to access endpoint prefix. See migration/v0.9.0.md for what changed.

More examples

• examples/vm-template — build a qemu template from a cloud image: download, disk import, cloud-init, resize, convert.
• examples/vm-refs — act on a VM through a zero-request ref, next to the fetch pattern, and when to use which.
• examples/sdn — full SDN walkthrough: create a zone, vnet, subnet, controller, dry-run / apply / rollback.
• examples/term-and-vnc — websocket terminal and VNC proxy via a small Gin server.

Upgrading between releases

Per-release migration guides live in migration/. Each file describes the source-level changes when upgrading FROM the named release.

• migration/v0.6.0.md — upgrading from v0.5.x
• migration/v0.7.0.md — upgrading from v0.6.0 (the major cleanup release)
• migration/v0.9.0.md — task waits report failed tasks as errors; typed API errors (*APIError); non-2xx responses that used to be ignored now return errors

Developing

This project relies on Mage for cross os/arch compatibility, please see their installation guide.

Unit Testing

Run mage test to run the unit tests in the root directory.

Integration Testing

To run the integration testing suite against an existing Proxmox API set some env vars in your shell before running mage testIntegration. The integration tests will test logging in and using an API token credentials so make sure you set all five env vars before running tests for them to pass.

Please leave no trace when developing integration tests. All tests should create and remove all testing data they generate then they can be repeatably run against the same proxmox environment. Most people working on this package will likely use their personal Proxmox VE home lab and consuming extra resources via tests will lead to frustration.

Bash

export PROXMOX_URL="https://192.168.1.6:8006/api2/json"
export PROXMOX_USERNAME="root@pam"
export PROXMOX_PASSWORD="password"
export PROXMOX_TOKENID="root@pam!mytoken"
export PROXMOX_SECRET="somegeneratedapitokenguidefromtheproxmoxui"

mage test:integration

Powershell

$Env:PROXMOX_URL = "https://192.168.1.6:8006/api2/json"
$Env:PROXMOX_USERNAME = "root@pam"
$Env:PROXMOX_PASSWORD = "password"
$Env:PROXMOX_TOKENID = "root@pam!mytoken"
$Env:PROXMOX_SECRET = "somegeneratedapitokenguidefromtheproxmoxui"

mage test:integration