Homelab & Proxmox on Luther Monson

Breaking Changes Without Breaking Trust: Five Years to go-proxmox v0.8

Sun, 04 Oct 2026 19:40:00 -0700

go-proxmox had its first commit in June 2021 and v0.8.2 went out on September 30th. In between there were 366 commits and 43 people besides me with a merged PR. More to the point of this post, there are downstream projects that I don’t control pinning it in their go.mod. IONOS’s Cluster API provider and Sidero’s Omni Proxmox provider are both on v0.8.1 today. A library with users like that gets judged less on its API. It gets judged more on what happens to their build when they bump the version. I didn’t always get that right, so here is the history, measured.

Rescuing a Windows Dynamic Disk Over USB with WSL2 and USB/IP

Sat, 01 Aug 2026 13:15:00 -0700

I pulled a 1 TB NVMe out of an old Windows box, dropped it in a USB enclosure and plugged it in. Windows showed nothing. No drive letter, no “initialize this disk” prompt, nothing in Explorer. Disk Management listed it as Invalid. The enclosure’s booklet said to “bring the disk online”, which silently did nothing. The data was completely intact. Windows was refusing on policy grounds, not because anything was broken. Getting it back meant going around the Windows storage stack entirely. I handed the raw USB device to a Linux kernel that doesn’t share Windows’ opinions.

Five Ways to URL-Encode an SSH Key (and Why Proxmox Rejects Them)

Tue, 28 Jul 2026 20:12:00 -0700

Issue #144 on go-proxmox was opened in April 2024 with the title “Weird sshkeys SSH public key validation error”. It is one of my less proud threads. It’s thirteen comments of people, including me, trying to get a public key into a cloud-init VM through the API. The working answer took more than a year to show up. The fix that finally landed in May is one line. Here’s why it took so long.

Two Small go-proxmox Fixes: A Watch Channel That Never Closed, and WithRetry

Sat, 11 Jul 2026 17:26:00 -0700

Here are two changes from the v0.5 to v0.7 stretch of go-proxmox. They’re too small for a post each. They’re worth knowing about if you write long-running tooling against Proxmox. One is a bug in code I wrote about in 2022. The other is a feature that replaces a retry loop everybody was writing for themselves.

The channel that only closed when things went well

In 2022 I wrote up how tasks and Watch work. Watch returns a channel of log lines. A goroutine tails the task log until the task stops. Then it closes the channel so you can range over it. Here is the tail loop from that post:

Maintaining an Open-Source Library With AI Agents: AGENTS.md and the Rule They Kept Breaking

Sat, 27 Jun 2026 18:47:00 -0700

On May 9th I merged #264. It added an AGENTS.md to go-proxmox and a stub CLAUDE.md that just points at it. The next six weeks ran through the v0.8.0 migration guide on June 15th. In that time main took 77 commits and +31,794 / -1,144 lines. The repo went from 84 to 186 .go files. Endpoint coverage went from 30% to 100% of the Proxmox API. Most of that code was typed by coding agents, a lot of it by several at once. This is what that looked like from the maintainer’s chair. It’s mostly the parts that went wrong, because that’s where AGENTS.md got its content.

Proxmox JSON, Part 2: null PIDs, 1.12589990684262e+15 and net10

Tue, 23 Jun 2026 20:31:00 -0700

In 2023 I wrote about why go-proxmox has StringOrInt and friends. Proxmox sends the same number quoted in one place and bare in another, so the client has types that accept both. That post ended on a pretty confident note. Since then three more shapes of “the JSON is valid and Go still won’t take it” have come in. One of them is a bug I’d already fixed once and then reintroduced myself.

Your Zero Value Just Turned Off My TLS Verification: omitempty, Go Defaults and Proxmox

Sat, 13 Jun 2026 19:52:00 -0700

Every Go developer knows omitempty drops zero values. What takes longer to sink in is that a plain bool only has two states. A caller filling in an options struct means one of three:

“set it true”
“set it false”
“I didn’t touch this, do whatever the server does by default”

With omitempty you lose “false”. Without it you lose “didn’t touch it”. In go-proxmox we managed to ship both bugs, in that order. The second one quietly turned off TLS certificate verification for anyone downloading ISOs through the API.

From 52% to 100%: Measuring a Go Client Against the Proxmox API Schema

Sun, 07 Jun 2026 21:36:00 -0700

For five years the honest answer to “how much of the Proxmox API does go-proxmox cover?” was “a lot of it? the parts people asked for?”. Issues would come in for endpoints that didn’t exist in the client. I’d have no idea how many more were missing. At the end of May I finally built the thing that answers the question. Three days after the first run the answer was 100%. The more interesting part is how many times the measuring stick was wrong on the way there.

Cloud-Init ISOs in Pure Go with go-proxmox

Sat, 06 Jun 2026 15:20:00 -0700

Proxmox’s built-in cloud-init support is fine for the basics: a user, an SSH key, an IP config. It falls apart the second you want your own user-data, vendor-data or a real network-config. The GUI and the ci* options only expose a handful of fields. The escape hatch is cicustom pointing at snippet files, and that means getting files onto the Proxmox host’s filesystem first. The usual alternative is building a nocloud ISO yourself with genisoimage or mkisofs. That means a system dependency on whatever machine runs your automation. You get a different package name on every OS and a subprocess to babysit.

Staying Logged In to Proxmox: Ticket Renewal, Expiry and Where API Tokens Stop

Sun, 31 May 2026 20:24:00 -0700

Back in 2023 I wrote up how go-proxmox logs in and ended it with a shrug. Once a session existed the client never logged in again. A ticket-based client died at the two hour mark. My advice was “use an API token for anything long running”. It took until this month to fix that properly. It took three PRs from two of us to get there. Here’s the whole arc, plus the one place where an API token isn’t an option at all.

Proxmox Doesn't Know What Type a Number Is

Sat, 25 Nov 2023 20:05:00 -0700

Every couple of months somebody opens an issue on go-proxmox with a title that starts with json: cannot unmarshal string into Go struct field. The most recent one was fixed last week. It’s the same root cause every time. The Proxmox VE API is backed by Perl, and Perl doesn’t really care whether a scalar is a number or a string. The JSON encoder on the other end writes whatever the scalar happens to be at the time. So a field that is documented as an integer comes back as 2048 from one endpoint and "2048" from another. Sometimes it changes on the same endpoint depending on how the value got into the config.

Logging In to Proxmox From Go: Tickets, CSRF Tokens and API Tokens

Sun, 27 Aug 2023 19:18:00 -0700

I just spent a week of evenings on the access side of go-proxmox. Realms, groups, users and roles all landed. Before any of that, I reworked how a client gets its credentials in the first place. Proxmox gives you two different ways to authenticate. They behave differently enough that it’s worth writing down how each one works on the wire and what the client does with it.

Waiting on Proxmox: UPIDs, Tasks and WaitFor in Go

Sun, 20 Mar 2022 16:42:00 -0700

If you start automating Proxmox VE through the API, one thing trips you up first. Almost nothing you ask it to do is finished when the HTTP call returns. Start a VM, clone a template, download an ISO to storage, delete a disk… the response is a single string that looks like a typo. The actual work is happening in a worker process on the node. If your next call depends on that work being done, you have to go find out when it’s done.

Recreating Proxmox Ve Xtermjs in Go

Sun, 06 Feb 2022 21:54:53 -0700

Part of a hobby of mine is running a home lab and using on Proxmox VE to do the virtualization. Since I work in the space I’m slowly trying to build tooling around Proxmox that will let me use the home lab full time for work. Usually my work involves building Kubernetes management tooling. You can imagine waiting for public cloud APIs all day can take away hours of your day. That’s at cost to your employer for both your time and the compute resources.