Proxbase MCP server

Proxbase

Real Proxmox VE clusters on your Linux machine in about three minutes, for labs, demos and CI.

Proxbase starts every node as a QEMU/KVM virtual machine, installs it from the official Proxmox VE ISO with the automated installer, and joins the nodes into a cluster through the Proxmox API, with ZFS or Ceph storage, internal networks and an API token ready for Terraform or Ansible. No root, no Docker, no manual clicks.

$ proxbase create lab --nodes 3
…
created in 2m56s
Cluster lab: ready, quorate: yes, switch: running
NODE  VM       CLUSTER  IP           WEB UI                   SSH
pve1  running  online   10.10.10.11  https://127.0.0.1:18001  127.0.0.1:18101
pve2  running  online   10.10.10.12  https://127.0.0.1:18002  127.0.0.1:18102
pve3  running  online   10.10.10.13  https://127.0.0.1:18003  127.0.0.1:18103

Features

nested virtualization lets you run guests inside the cluster.

• Real nodes: each node is a VM with its own kernel installed from the stock ISO;

for HEALTH_OK.

• Storage: ZFS pools per node, or hyperconverged Ceph (RBD and CephFS) that waits

link0/link1, Ceph public/cluster, migration), VLAN-aware and L2-only bridges, jumbo frames.

• Networking without root: several internal networks with roles (corosync

snapshots of the whole cluster, live snapshots that resume a running cluster in seconds, resumable creates.

• Lifecycle: start/stop, add and remove nodes (with Ceph draining), consistent

latency and loss, to test HA, fencing and Ceph recovery.

• Fault injection: power loss, hung nodes, pulled cables, network partitions,

and the bpg/proxmox Terraform provider, -o json and --progress json for scripts, and a GitHub Action for CI that can cache a ready cluster as a template.

• Ready for automation: API token and CA export, proxbase env for shells, JSON

clusters, run commands on nodes, snapshot and inject faults through tools.

• For AI agents: proxbase mcp is an MCP server: agents create

under a minute (Ceph: 1.5 minutes), with a unique identity per node.

• Fast: --golden clones nodes from a cached base image: a 3-node cluster in

shutdown and a health check.

• Declarative: one YAML file with a JSON schema; every flag overrides a field.
• Docker Compose: proxbase up runs a cluster in the foreground with clean

Quick start

Requirements: Linux on amd64 with /dev/kvm, QEMU 7.2+ (qemu-system-x86_64, qemu-img) and about 4 GiB RAM per node. Nested virtualization is needed for guests inside the nodes.

go install github.com/virtbase/proxbase/cmd/proxbase@latest   # or see docs/install.md
proxbase doctor                                               # checks KVM, QEMU, memory, ports
proxbase create lab --nodes 3

Then open https://127.0.0.1:18001 (user root, password from proxbase env lab), or:

proxbase ssh lab pve2 -- pvecm status
eval "$(proxbase env lab)"            # PROXMOX_VE_ENDPOINT, PROXMOX_VE_API_TOKEN, …
proxbase destroy lab --yes            # removes everything

Usage

Shortened. The full README is on GitHub.