Proxbase

Proxbase

[CI] [Go version] [License]

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 2m56sCluster lab: ready, quorate: yes, switch: runningNODE  VM       CLUSTER  IP           WEB UI                   SSHpve1  running  online   10.10.10.11  https://127.0.0.1:18001  127.0.0.1:18101pve2  running  online   10.10.10.12  https://127.0.0.1:18002  127.0.0.1:18102pve3  running  online   10.10.10.13  https://127.0.0.1:18003  127.0.0.1:18103

Features

• Real nodes: each node is a VM with its own kernel installed from the stock ISO; nested virtualization lets you run guests inside the cluster.
• Storage: ZFS pools per node, or hyperconverged Ceph (RBD and CephFS) that waits for HEALTH_OK.
• Networking without root: several internal networks with roles (corosync link0/link1, Ceph public/cluster, migration), VLAN-aware and L2-only bridges, jumbo frames.
• Lifecycle: start/stop, add and remove nodes (with Ceph draining), consistent snapshots of the whole cluster, live snapshots that resume a running cluster in seconds, resumable creates.
• Fault injection: power loss, hung nodes, pulled cables, network partitions, latency and loss, to test HA, fencing and Ceph recovery.
• Ready for automation: API token and CA export, proxbase env for shells, JSON 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.
• For AI agents: proxbase mcp is an MCP server: agents create clusters, call the API, run commands on nodes, diagnose, reset to snapshots and inject faults through tools. A skill teaches them the workflow; in Claude Code: /plugin install proxbase --marketplace virtbase/proxbase.
• Fast: --golden clones nodes from a cached base image: a 3-node cluster in under a minute (Ceph: 1.5 minutes), with a unique identity per node.
• 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 shutdown and a health check.

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.mdproxbase doctor                                               # checks KVM, QEMU, memory, portsproxbase 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 statuseval "$(proxbase env lab)"            # PROXMOX_VE_ENDPOINT, PROXMOX_VE_API_TOKEN, …proxbase destroy lab --yes            # removes everything

Usage

proxbase create ceph --nodes 3 --storage ceph       # hyperconverged Cephproxbase create fast --nodes 3 --golden             # clone from a cached base imageproxbase create -f examples/networks.yaml           # separate networks and VLANsproxbase node add lab --count 1                     # grow the clusterproxbase node remove lab pve2                       # shrink it againproxbase stop lab && proxbase snapshot save lab baseproxbase snapshot restore lab base && proxbase start labproxbase env lab --format terraform                 # provider block for bpg/proxmoxproxbase fault partition lab pve3                   # isolate a node, then: fault clearproxbase status lab --check                         # exit code for CI and health checksclaude mcp add proxbase -- proxbase mcp             # let an AI agent drive proxbaseproxbase upgrade                                    # install the latest release

In GitHub Actions:

- id: pve  uses: virtbase/proxbase@v0          # KVM, QEMU, cache, create; outputs endpoint, api-token, env-file- env: {PVE_ENV: "${{ steps.pve.outputs.env-file }}"}  run: . "$PVE_ENV" && go test ./... -tags integration- if: always()  run: proxbase destroy ci --yes

A cluster file looks like this (everything has a default):

apiVersion: proxbase.virtbase.com/v1alpha1kind: Clustername: labnodes:  count: 3  defaults: {cpus: 4, memory: 4G, dataDisks: [{size: 32G}]}networks:  - {name: cluster, cidr: 10.10.10.0/24, roles: [corosync]}storage:  zfs: [{name: tank, raid: single}]

Documentation

Status and limits

Proxbase is young; the file format may change before v1.0. It is tested with Proxmox VE 9.2 on Debian 13 (QEMU 10.0, AMD). Clusters need a Linux host with KVM: macOS builds are experimental and Docker Desktop has no /dev/kvm. Nodes are reachable from the host through forwarded ports on 127.0.0.1; host-reachable bridge networking is designed but not implemented. Proxbase builds labs: it stores generated passwords and keys unencrypted in its state directory.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md and the code of conduct. Report security issues privately as described in SECURITY.md.

License

Apache-2.0