claude-proxmox-controller
# Claude Proxmox Controller
[](https://github.com/themechanic-dev/claude-proxmox-controller/actions/workflows/tests.yml)
**Your Proxmox VE hosts in one window — and Claude, working on them as far as you let it.**
Proxmox Controller is a desktop app for Windows and Linux. On its own it is a fast home for your hosts: containers
and virtual machines, consoles, files, snapshots, backups and graphs, without a browser or a web login. The magic is
**Claude Access**: Claude (Anthropic's AI) can look after your hosts — start and stop guests, create VMs that set
themselves up, schedule backups, read logs, run commands inside guests, copy files — through switches you set for each host and
requests you approve in a window of the app. You stay in charge of every step.
*by the mechanic — built together with Claude*
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/img/main-dark.webp">
<img src="docs/img/main-light.webp" alt="Proxmox Controller: a Proxmox host's page with its CPU, memory and storage, and the list of its containers and virtual machines">
</picture>
<br>
<em>A host at a glance: its CPU, memory and storage, and its containers and virtual machines.</em>
</p>
---
## Claude Access: AI on your servers, safely
Claude reaches your hosts only through this app, and only as far as each host's switches allow:
| Switch | What it opens | Default |
|---|---|---|
| Read | state, addresses, settings, snapshots, backups, tasks, graphs | On |
| Power | start, shut down, stop, reboot, wake | Ask |
| Change | new guests, settings, snapshots, backups, backup jobs | Ask |
| Destroy | deleting guests, snapshots, backups, Claude's backup jobs; jobs that prune old backups | Off |
| Host | the host's own power | Off |
| Console | the guest's screen: screenshots, keys, clicks, recordings | Off |
| Commands | commands inside guests (QEMU guest agent) | Off |
| Files | copying files to and from guests | Off |
| Host commands | shell commands on the Proxmox host (SSH) | Off |
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/img/access-dark.webp">
<img src="docs/img/access-light.webp" width="600" alt="The Claude Access window: the Claude apps connected, and the switches of a host — Read On, Power and Change Ask, the rest Off">
</picture>
<br>
<em>The Claude Access window: the Claude apps it connected, and one host's switches.</em>
</p>
Each switch is **Off** (refused), **Ask** (a window asks you: *Allow*, *Allow on this guest for an hour* — another
guest is asked about again — or *Deny*) or **On**. The approval window wears yellow-and-black warning stripes, so it is never lost among other windows.
Claude never sees a password: where one is needed, the app asks **you** for it in its own window. Every request is
logged with the reason Claude gave. Claude's token on each host holds only the Proxmox privileges its open switches
need. The full list of tools is in [docs/claude-access.md](docs/claude-access.md).
The switches govern Claude as it works through this app. A program that runs as you on your computer (Claude Code
with a shell of its own, too) is outside them: it can read the app's files — the hosts' API tokens and the app's SSH
key among them, which are not encrypted, only readable by you alone.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/img/ask-dark.webp">
<img src="docs/img/ask-light.webp" width="700" alt="The approval window, framed in warning stripes: Claude Desktop asks to start VM 101, with its reason, and Deny, Allow This Kind for 1 Hour and Allow">
</picture>
<br>
<em>An approval window: Claude asks to start a VM and says why. You answer.</em>
</p>
It works with Claude Desktop and Claude Code (the app connects them for you).
Under the hood, Claude Access is a local [MCP](https://modelcontextprotocol.io) server: the app registers it with Claude Desktop and Claude Code for you, and every tool call passes through the switches above.
## Without AI
Everything works without Claude too:
- **Hosts** — one or many, with Wake-on-LAN, the host's console and upgrade, and its CPU, memory and storage.
- **Guests** — start, shut down, stop, reboot, many at once; notes, tags, boot order; edit cores, memory, disks,
display, sound and USB devices.
- **Consoles** — a built-in one (with **Paste…**: text typed into the guest key by key, even in an installer), or
SPICE through virt-viewer for sound, clipboard and USB. **Record** any console as a video (MP4, with the VM's
sound when it has SPICE), for you or for Claude — a desktop, a server's text screen or a container.
- **Files** — this computer on one side, a VM or container on the other: send, receive, drag, and a right-click menu
with Rename, Delete, Properties, Permissions and **Edit** (open a guest's file in your own editor, save, send back).
- **New VMs that set themselves up** — Windows 11 with no setup questions; ready-made Ubuntu Desktop (with Remote
Desktop) or Server in minutes; Ubuntu Server from its ISO, installing itself; a static IP if you want one.
- **Install Guest Agent** — for VMs that lack it, typed into their console for you.
- **Snapshots, backups, scheduled backup jobs, graphs.**
- **Updates** — a striped tab tells you when a new version is out; one click installs it.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/img/newvm-dark.webp">
<img src="docs/img/newvm-light.webp" width="450" alt="The New VM window: an Ubuntu Server ISO that installs itself, with a user, CPU cores, memory, disk and network">
</picture>
<br>
<em>A new VM from an Ubuntu Server ISO that installs itself — nothing to answer.</em>
</p>
## Install
- **Windows 10/11** — download the setup from [themechanic.store/controller](https://themechanic.store/controller)
and run it. It installs for your user and offers to add virt-viewer (the SPICE console).
- **Ubuntu / Debian** — download the `.deb` from the same page and open it, or install from the terminal (the
package brings virt-viewer with it):
```bash
sudo apt install ./proxmox-controller_1.2.0_amd64.deb
```
- **Ubuntu / Debian, from its apt repository** — it then updates with the rest of the system:
```bash
wget -qO- https://themechanic.store/apt-controller/proxmox-controller.gpg | sudo tee /usr/share/keyrings/proxmox-controller.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/proxmox-controller.gpg] https://themechanic.store/apt-controller ./" | sudo tee /etc/apt/sources.list.d/proxmox-controller.list
sudo apt update && sudo apt install proxmox-controller
```
The package is built on Ubuntu 24.04 and runs there and on newer releases (tested on Ubuntu Desktop 26.04).
Each host needs a Proxmox API token (Help in the app shows how to make one).
## From the source
Linux, Python 3.12+:
```bash
./install.sh
```
The tests: `.venv/bin/python -I tools/run_tests.py`. The packages: `packaging/windows/build.py` (on Windows, with
PyInstaller and Inno Setup) and `packaging/linux/build_deb.py` (on Ubuntu 24.04, with PyInstaller and dpkg-deb).
## License
[MIT](LICENSE) — the code is open for anyone to read, use and build on.
TDQS
Scored across 47 tools
Most tools target a clearly distinct resource+action: power (guest/host/bulk/wake), snapshots (list/take/rollback/delete), backups (list/now/job CRUD/restore), guests (create/clone/details/usage/edit/delete). A few pairs are close — console_send vs console_type_password, guest_power vs bulk_power, backup_now vs run_backup_job — but the descriptions draw sharp lines (e.g. passwords only via the user's window, bulk = ordered batch as one task). No genuinely indistinguishable duplicates.
The dominant pattern is verb_noun in snake_case (list_guests, create_vm, delete_snapshot, edit_backup_job, grow_disk). Deviations are noun-prefixed families with a consistent noun (console_*, guest_*, host_*, list_backup_jobs) plus a couple like task_log; readability stays high and no camelCase mixing occurs.
47 tools is heavy and sits at the upper edge of what a single agent can hold in view, with several near-neighbours (backup job create/edit/delete/run, list_*, console_*) that drive the count up. The breadth is at least defensible for Proxmox management (VMs, containers, snapshots, backups, console, file transfer, host ops), so it is borderline rather than bloat.
Lifecycle coverage is strong: guest create/clone/edit/delete, snapshot take/list/rollback/delete, backup now/list/schedule/edit/delete/restore, plus console interaction, guest-agent commands, file transfer and host power. Remaining gaps are modest — no VM migration, no convert-to-template, no deletion of downloaded ISOs/templates, and disk handling is grow-only.