Skip to content
Conduit

mcp server

proxbase

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

virtbase/proxbasecommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • Docker Desktop
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "proxbase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/virtbase/proxbase:0.2.1"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 17, 2026

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 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

  • 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, run commands on nodes, snapshot and inject faults through tools.
  • 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.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

proxbase create ceph --nodes 3 --storage ceph       # hyperconverged Ceph
proxbase create fast --nodes 3 --golden             # clone from a cached base image
proxbase create -f examples/networks.yaml           # separate networks and VLANs
proxbase node add lab --count 1                     # grow the cluster
proxbase node remove lab pve2                       # shrink it again
proxbase stop lab && proxbase snapshot save lab base
proxbase snapshot restore lab base && proxbase start lab
proxbase env lab --format terraform                 # provider block for bpg/proxmox
proxbase fault partition lab pve3                   # isolate a node, then: fault clear
proxbase status lab --check                         # exit code for CI and health checks
claude mcp add proxbase -- proxbase mcp             # let an AI agent drive proxbase

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/v1alpha1
kind: Cluster
name: lab
nodes:
  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

Topic
Getting startedFirst cluster, web UI, credentials
InstallationPackages, Homebrew, container image, verifying releases
ConfigurationEvery field, default and limit
Networking · Storage · LifecycleHow it works and what to expect
Fault injection · Golden imagesBreaking the cluster on purpose, faster creates
CI and automation · MCP serverGitHub Action, JSON progress, AI agents
Docker · CLI reference · Troubleshooting
ArchitecturePackages, create flow, state on disk
ExamplesReady-to-use cluster files for common setups

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

↑↓ navigate openesc close