Delegating Proxmox Virtual Environment Management to Claude Code

This article was automatically translated from Japanese by AI.

My Custom PC and Server Management

I run Proxmox as a virtualization platform on my custom-built PC, running multiple VMs for different purposes. I have Windows installed for occasional PC gaming, and an Ubuntu VM with GPU passthrough for data competitions like Kaggle — it’s become a fairly complex setup.

However, managing this kind of virtualized environment is honestly not my strong suit, coming from a software-layer background. While I can handle the straightforward Proxmox use cases without issues, I’d stumble whenever I tried anything slightly complex, and hardware-related configurations were always a struggle.

Since Claude Code came along, I’ve been delegating almost all of my Proxmox server management to it. For example, I can hand off SSD failure investigations like this:

In this article, I’ll briefly introduce how to set up Claude Code for Proxmox management and share some real-world use cases.

Setup

It’s straightforward — just install Claude Code on the Proxmox host environment. Since Proxmox’s base OS is Debian, you can install Claude Code the same way as any standard Linux environment. The basic configuration is the same as regular development use, but since it has the ability to make destructive changes to VMs and other resources, it’s advisable to have a human review commands before execution.

Additionally, installing Tailscale alongside it allows you to SSH directly from your local terminal. This eliminates the hassle of opening a shell through the Proxmox Web UI in a browser, and using Claude Code directly from a terminal is far more comfortable.

Running Various Tasks with Claude Code

Here are some examples of tasks I regularly delegate to Claude Code:

• Creating VMs/LXCs: Creating new VMs and containers from ISO images or templates. GPU passthrough setup can get complex, but it handles everything from VFIO configuration to initramfs updates.
• Changing core counts: Adjusting CPU core counts and memory allocated to VMs. While it’s just a matter of changing settings with qm set and restarting the VM, it conveniently checks the current allocation before suggesting appropriate values.
• Adding disks: Creating new storage pools and adding disks to VMs. It handles the entire workflow from LVM thin pool creation to Proxmox registration and VM assignment in one go.
• SSD failure response: Checking SSD SMART information to diagnose errors and assisting with data evacuation from drives showing signs of failure. It interprets output from nvme smart-log and smartctl and explains the situation, so you quickly have the information needed to make decisions.

Claude Code on the Proxmox host can perform virtually all virtual environment operations through various CLI commands. Below is a list of commands actually in use (this was compiled by Claude Code from past sessions).

Category	Command	Purpose
VM management	qm create/set/start/stop/status	Create, configure, start/stop VMs
	qm resize/move_disk/importdisk	Resize, move, import disks
	qm terminal/guest cmd	Console access, guest operations
LXC management	pct create/enter/set	Create, enter, configure containers
Proxmox	pvesm status/add	Storage management
	pveum role add/user add/aclmod	User and permission management
LVM	pvs/vgs/lvs	PV/VG/LV status checks
	pvcreate/vgcreate/lvcreate	Create PV/VG/thin pools
	lvremove/wipefs	Remove LVs, initialize disks
SSD diagnostics	nvme smart-log/error-log/self-test	SMART info, errors, diagnostics
	smartctl -a	Detailed SMART data
HW info	lspci/lsblk/lscpu/nproc	Check GPU, disk, CPU
GPU passthrough	modprobe/vfio config/update-initramfs	VFIO, disable nouveau
Disk operations	mount/umount/fdisk/kpartx/losetup	Mount images, check partitions
Network	nmap/arp/ip neigh/curl	Port scanning, connectivity checks
Guest internal	fstrim/growpart/lvextend/resize2fs	TRIM, partition expansion

Claude Code combines these commands as needed depending on the situation. For example, when adding a disk, it handles the entire flow from checking LVM status, creating storage, assigning it to a VM, and expanding the partition inside the guest — so there’s no need to memorize individual commands.

Accumulating Context by Automatically Keeping Work Logs

Server management tasks tend to be infrequent, and as humans, we inevitably forget what we did last time and why we chose a particular configuration. So I’ve adopted the practice of having Claude Code record work logs and decision rationale after completing any task. It writes out information like which commands were executed, why certain settings were chosen, and what caveats to be aware of into Markdown files. This is perhaps the most quietly appreciated feature — Claude Code diligently documents things that humans would tend to skip out of laziness. Moreover, these accumulated logs serve as valuable context for Claude Code itself, leading to improved accuracy in future sessions.

Claude Code Knows Everything, but Won’t Always Do It for You

On the other hand, there have been failure cases from delegating to Claude Code. When migrating a VM’s disk onto a thin pool, the discard=on option was not set, which meant file deletions inside the VM were not reflected in the thin pool. Eventually, the thin pool’s Data% reached 99%, causing I/O errors and VM crashes. With LVM thin provisioning, configuring TRIM propagation from guest to host is essential, but there are cases where Claude Code fails to account for such implicit prerequisites.

That said, I don’t want to jump to the easy conclusion that we simply shouldn’t rely on it too much. Claude Code can respond to user requests when explicitly stated, but it’s not great at implicitly understanding the context behind a request and proactively addressing it. When delegating tasks, you need to explicitly specify things like how you plan to use it, what the ideal state looks like, and conversely, what outcomes you want to avoid. It’s also helpful to structure your requests so that Claude Code asks you clarifying questions about these details, or to document them in CLAUDE.md.

Conclusion

Managing virtualized environments requires a broad range of knowledge, but using an agent like Claude Code significantly reduces that burden. The time spent looking up command usage and assembling procedures has virtually disappeared — you just describe what you want in natural language. The mental overhead of server management has decreased, and I feel I’ve been able to tackle minor tasks that I previously avoided due to the hassle.

As for future challenges, it comes down to improving the accuracy of task execution. By continuing to keep work logs and enriching the context available to Claude Code — through collecting metrics and introducing monitoring tools — I believe management accuracy will continue to improve.