NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules · #2994 by repository stars
Last release 7 days ago
30 Sep 2026
Ships fairly regularly
a new release about every 3 weeks
Some releases are documented
notes for 11 of 21 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
156 releases · first in 2021
One column per quarter.
docs: add vm-template example, document the options-vs-config split by @luthermonson in #345
Full Changelog: v0.8.1...v0.8.2
Nothing published for this version
AgentFileWrite no longer double-encodes content ( #343 ). It base64-encoded the payload and sent PVE's encode=1 , so PVE encoded it a second time and
AgentFileWrite no longer double-encodes content (#343). It base64-encoded the payload and sent PVE's encode=1, so PVE encoded it a second time and QGA's single decode left base64 text on disk — corrupting any file written this way (configs, keys). Now sends the base64 payload with encode=0 so QGA reproduces the original bytes. Binary-safe.VirtualMachine.Delete signature change — gains a second parameter *VirtualMachineDeleteOptions . Pass nil to preserve existing behaviour. See migratio
VirtualMachine.Delete signature change — gains a second parameter *VirtualMachineDeleteOptions. Pass nil to preserve existing behaviour. See migration/v0.8.0.md for details and before/after examples.
// before
task, err := vm.Delete(ctx)
// after
task, err := vm.Delete(ctx, nil) // same behaviour
task, err := vm.Delete(ctx, &proxmox.VirtualMachineDeleteOptions{
Purge: true,
DestroyUnreferencedDisks: true,
})VirtualMachineDeleteOptions — pass purge, skiplock, destroy-unreferenced-disks to VirtualMachine.Delete (#340)VirtualMachine.Ping now correctly propagates config-fetch errors (#339)errors.Is) (#341)See migration/v0.8.0.md.
Full changelog: v0.7.1...v0.8.0
⚠️ Breaking changes & migration
v0.7.1 is a correctness patch. A full audit of every exported response type in types.go against PVE's apidoc.json and QGA's qga/qapi-schema.json surfaced eight long-standing schema mismatches — six of them silently no-op'd on the wire (wrong JSON tag, wrong scalar type, or a field name PVE never emitted). The apparent breaks below are functionally additive: the new field is the first one that has ever worked.
Two source-level breaks, both on StorageContent. See migration/v0.7.1.md for the full upgrade walkthrough.
| Change | Upgrade |
|---|---|
StorageContent.Encryption (string, tag encryption) → StorageContent.Encrypted (tag encrypted) |
rename the field reference; old value was always "" because the tag never matched the upstream key |
StorageContent.Verification string → *StorageContentVerification{State, UPID} |
dereference and read .State / .UPID; old value was always "" because PVE returns a nested object |
The Go field still exists and code still compiles; only the wire format changed. Switch to the replacement to get real behavior.
AgentNetworkIPAddress.MacAddress deprecated → read iface.HardwareAddress (the QGA schema has never had a per-IP mac-address field). Closes #336.FirewallNodeOption.Ntp / FirewallVirtualMachineOption.Ntp deprecated → use NDP. The PVE option is ndp (Neighbor Discovery Protocol); ntp was a typo shipped since v0.1.x and never had any effect.Tags fixed so the fields finally unmarshal from PVE:
CephMonMap.DisallowedLeaders — strip trailing ": " inside the quoted tagCephMonMap.RemovedRanks — sameFirewallRule.IcmpType — icmp_type → icmp-type (ICMP rules now round-trip correctly)NewClient(...) with no options still behaves identically to v0.7.0WithProxy, WithRetry, WithEagerAuth, …) unchangedSee v0.7.0...v0.7.1 once tagged.
Full Changelog: v0.7.0...v0.7.1
⚠️ Breaking changes & migration
v0.7.0 is the major cleanup release. Three years of accumulated patterns get
resolved into a consistent shape:
mtunnelwebsocket builders and file-restore/download). The v0.6.0 release sat at 81%; the v0.7.x cycle closed the cluster gap entirely with the SDN sweep (#320), the bulk-action / ceph-flags / qemu-cpu-models / options / log / notifications / HA arm-disarm cleanup (#322), and the rest.WithTimeout, WithInsecureSkipVerify, WithRootCAs, WithRootCAFile, WithClientCertificate, WithOTP, WithDefaultRealm, WithEagerAuth, WithProxy, WithProxyFromEnvironment, WithRetry (+ helpers), WithRequestInterceptor. All compose with WithHTTPClient regardless of option order. README has lab + production usage examples.parent.Resource(id) → *Resource getter shape that ceph already used in v0.6.0. The full inventory is in AGENTS.md.*T; ~25 bool-on-wire fields are now IntOrBool so they round-trip both true/false and 1/0. proxmox.Ptr(v) is the inline helper for the pointer fields.VirtualMachineConfig / ContainerConfig. Every numbered Net0..9, SCSI0..30, IDE0..3, SATA0..5, VirtIO0..15, USB0..14, HostPCI0..9, IPConfig0..9, Numa0..9, Parallel0..2, Serial0..3, Unused0..9 is gone. The maps populated by UnmarshalJSON (Nets, SCSIs, IPConfigs, …) are now the authoritative shape. PVE actually returns more indices than the explicit fields ever covered (net0..net31, scsi0..scsi30, unused0..unused255) — the old shape was silently dropping data.proxmox.CSV type for PVE fields serialized as comma-joined strings on the wire (most notably SDNZone.Nodes and .Peers).Subdirs methods on *Cluster and *Node for ACL-filtered directory-index probes. Use them to discover what an API token actually has permission to read without try-and-403 against every endpoint.This is a heavy release for source compatibility. The breaks are concentrated in three areas: the snapshot/firewall instance-pattern refactors, the dropped indexed device fields, and the config-struct pointerization sweep. Most fixes are mechanical.
Read migration/v0.7.0.md for the complete walkthrough — themed sections with before/after code for each break. The short version:
| Theme | Fix shape |
|---|---|
| Snapshots refactored | vm.DeleteSnapshot(ctx, "s") → vm.Snapshot("s").Delete(ctx); same pattern for Get/Update/Rollback/Config. Snapshots(ctx) returns []*VirtualMachineSnapshot. |
| Firewall rules refactored | vm.FirewallGetRule(ctx, 0) → vm.FirewallRule(ctx, 0). vm.FirewallRulesUpdate(ctx, rule) → rule.Update(ctx, opts). Same on *Container and *Node. |
| Indexed device fields | cfg.Net0 = "..." → cfg.Nets["net0"] = "..." (or send via VirtualMachineOption{Name: "net0", Value: "..."}). All Merge* helpers gone — the maps ARE the authoritative form. |
| Pointerized config fields | cfg.Memory = StringOrInt(4096) → cfg.Memory = proxmox.Ptr(StringOrInt(4096)). Full field list in the migration doc. |
| Bool → IntOrBool | opts.Enable = true → opts.Enable = proxmox.IntOrBool(true). Full list in migration doc. |
Client no longer comparable |
clientA == clientB (value comparison) doesn't compile. Pointer comparison still works. |
If you're upgrading from v0.5.x, also read migration/v0.6.0.md for the small set of v0.6.0 breaks.
NewClient(url, WithCredentials(...)) and NewClient(url, WithAPIToken(...)) with no other options — every new client field has a zero-value-safe code path. Upgrading without adopting any new option produces no behavior change.WithEagerAuth, the existing /access/ticket-after-401 sequence is unchanged.Full Changelog: v0.6.0...v0.7.0
⚠️ Breaking changes & migration
This is a coverage-and-correctness release. v0.6.0 lifts overall PVE API coverage substantially — /access, /pools, /nodes/{qemu,lxc,ceph,sdn,disks,apt,services,subscription,replication,time,dns,certificates,storage,agent,disks}, and /cluster/{acme,jobs,mapping,metrics,notifications} are now fully or nearly fully wrapped — and fixes a handful of latent bugs that hand-written PVE response assumptions had been hiding.
A new mage endpoints:coverage tool is included for tracking progress against the live PVE schema. AGENTS.md codifies the conventions (singleton-vs-instance handles, pointer fields for PVE-defaulted attributes) used across the new wrappers.
Four exported-surface changes require source updates:
Container.Delete requires options// before
task, err := container.Delete(ctx)
// after
task, err := container.Delete(ctx, nil)
// or, to exercise the new flags:
task, err := container.Delete(ctx, &proxmox.ContainerDeleteOptions{
Force: proxmox.IntOrBool(true),
Purge: proxmox.IntOrBool(true),
DestroyUnreferencedDisks: proxmox.IntOrBool(true),
})Closes #149 — previously there was no way to force-delete a locked container or purge job entries. See #262.
Container.UpdateSnapshot requires options// before
err := container.UpdateSnapshot(ctx, "snap1")
// after
err := container.UpdateSnapshot(ctx, "snap1", nil)
// or to set a description:
err := container.UpdateSnapshot(ctx, "snap1", &proxmox.ContainerSnapshotUpdateOptions{
Description: "pre-upgrade baseline",
})From #277.
CephMon reshapeCephMon was previously the /cluster/ceph status row shape; in v0.6.0 it is the instance handle for /nodes/{node}/ceph/mon/{monid} endpoints. The cluster-status reader fields (CrushLocation, Priority, Weight, PublicAddr, PublicAddrs) are gone.
If you were reading mon status from /cluster/ceph results, the equivalent shape now lives in the appropriate cluster ceph response type. For the node-level mon API:
mon := node.CephMon("0") // *CephMon instance handle
task, err := mon.Delete(ctx) // node-level mon operationsFrom the /nodes/{node}/ceph 100% sweep — see #307.
SDNZone.Nodes type change + new CSV typePVE returns nodes (and peers) as a comma-joined string, not a JSON array. v0.5.x's []string typing caused cluster.SDNZones() to fail outright on any zone with assigned nodes:
json: cannot unmarshal string into Go struct field SDNZone.nodes of type []string
// before — actually broken at runtime
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // []string
// after
zones, _ := cluster.SDNZones(ctx)
for _, n := range zones[0].Nodes { ... } // proxmox.CSV — still iterates fine
// callers passing zone.Nodes to []string-typed APIs need an explicit conversion:
manyNodes := []string(zones[0].Nodes)CSV is a []string named type with custom Marshal/Unmarshal that accepts both "a,b,c" and ["a","b","c"] on the wire and emits comma-joined strings. From #297 (thanks @kernel-sanders).
Full Changelog: v0.5.1...v0.6.0
pins go-diskfs at v1.9.3 to fix joliet bugs
Full Changelog: v0.5.0...v0.5.1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
feat: add Joliet extension to cloud-init ISO for Windows support by @luthermonson in #256
Full Changelog: v0.4.1...v0.5.0
Update VNet Tag type to uint32 and add max VNet Tag test case by @kernel-sanders in #244
Full Changelog: v0.4.0...v0.4.1
Nothing published for this version
Nothing published for this version
fix: vm merge devices by @sergelogvinov in #232
Full Changelog: v0.3.2...v0.3.3
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix: simplify network interface retrieval in AgentGetNetworkIFaces by @alperencelik in #230
Full Changelog: v0.3.1...v0.3.2
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →