VMGateway
Allows managing Proxmox VE clusters, including cloning templates, scheduling and leasing VMs, retrieving VM status and credentials, capturing VNC console screenshots, and destroying VMs when leases end.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
VMGateway
Give your coding agent any operating system, on demand.
VMGateway is a small lease-based service that sits between AI agents (Claude Code or anything that speaks MCP or HTTP) and your own hypervisors. An agent asks for "Windows 11 on ARM, 4 vCPU, 8 GB, for two hours"; the gateway picks a host with room, clones a template, injects fresh credentials, waits until the machine is reachable, and hands back the IP, ports and login. When the lease ends, the VM is destroyed.
Agents never see hypervisor passwords, host IPs or API tokens. Each user has an API key.
Claude Code ──MCP──┐ ┌── Proxmox VE cluster (Linux / Windows x86_64)
scripts ─────REST──┼──► VMGateway ──────────┼── Tart on a Mac (macOS / Linux ARM64)
│ leases · scheduler └── Hyper-V on Windows (Windows on ARM)
│ reaper · SQLiteFeatures
One API, three hypervisors. Proxmox VE (REST API token), Tart (SSH), Hyper-V (SSH + PowerShell 7).
Fast clones. PVE linked clones, Tart APFS clones, Hyper-V differencing disks. Measured on the author's lab: Ubuntu on PVE ~19 s, Ubuntu ARM on Tart ~13 s, macOS ~26 s, Windows 11 on PVE ~25 s, Windows 11 ARM on Hyper-V (first boot through OOBE) ~3 min.
Unattended credentials. cloud-init (Linux), unattend.xml (Windows VHDX), or a template's built-in account. Users can also choose their own username/password; the gateway creates the account after boot.
Leases. TTL 10 min – 72 h (default 2 h), renewable. A reaper destroys expired VMs, and a reconciler removes orphaned
vmgw-*VMs after crashes. VMs without thevmgw-prefix are never touched.Scheduling. Picks the node with the most free memory, respects per-node
max_vmsand Apple's two-running-macOS-VMs limit (counting VMs the gateway did not create).Multi-user. Per-user API keys (stored hashed), per-user lease quotas, admins see everything.
Screenshots.
screenshot_vmreturns the VM's console as an image, even before anyone logs in: PVE through its VNC websocket, Tart through Virtualization.framework's VNC server, Hyper-V through WMI. Agents can see GUI state without an RDP/VNC client. Displays are kept awake so captures are never blank.MCP + REST. MCP over Streamable HTTP at
/mcp(official Python SDK v2), REST at/v1.
Related MCP server: proxmox-mcp
Quick start
git clone https://github.com/joshhu/VMGateway && cd VMGateway
uv sync
cp config.example.yaml config.yaml # describe your hosts and templates
cp .env.example .env # secrets referenced by config.yaml
uv run vmgw user add alice --admin # prints alice's API key once
uv run vmgw serveConnect Claude Code:
claude mcp add --transport http vmgw http://<gateway>:8000/mcp \
--header "Authorization: Bearer <api key>"Then just ask: "Spin up a Windows 11 ARM VM, take a screenshot of the Settings app, then destroy it."
Docker
mkdir -p data keys && cp ~/.ssh/<mac key> ~/.ssh/<windows key> keys/
docker compose up -d --build
docker compose exec vmgateway vmgw user add alice --adminIn config.yaml, point key_path at /keys/<file>.
Preparing the hypervisors
The gateway clones existing templates. These helpers create what it needs.
Proxmox VE
# Least-privilege user + API token. Leased VMs live in pool "vmgw", templates in "vmgw-templates".
ssh root@pve 'bash -s' < scripts/pve/bootstrap-token.sh # prints TOKEN_SECRET=... → .env
# Ubuntu 24.04 / 22.04 cloud-init templates with qemu-guest-agent baked in (edit the node list first).
ssh root@pve 'bash -s' < scripts/pve/build-ubuntu-templates.sh
# Existing templates you want to offer must be in the template pool:
ssh root@pve 'pveum pool modify vmgw-templates --vms 102,210'local-lvm is node-local, so linked clones only work on the node that holds the template: list one
source per node in the template's sources. Windows templates need the QEMU guest agent installed
(the gateway reads the IP from it).
Tart (macOS host)
Install Tart, enable Remote Login for the gateway's SSH key.
Bridged networking (
bridged_interface: en0) gives VMs LAN addresses agents can reach.IPs are discovered via the Tart guest agent, falling back to ARP.
For macOS templates with a
vncendpoint, the gateway turns on Screen Sharing in each new VM.VMs run with
--vnc-experimental(host-side VNC, no window on the Mac) soscreenshot_vmworks for every guest; the gateway reaches it through its SSH connection.
Hyper-V (Windows host)
Enable OpenSSH Server, make PowerShell 7 available, and authorize the gateway's key for an account in Hyper-V Administrators and Administrators.
Template: a generalized (OOBE) Windows VHDX. Mark it read-only; every VM is a differencing disk on top.
The gateway writes
unattend.xmlinto the new disk (skip OOBE, create the lease's admin account), boots it with the network disconnected (otherwise OOBE may install a zero-day update, reboot and stop at the interactive account page), waits over PowerShell Direct, connects the network, then enables RDP (and OpenSSH if requested).OpenSSH Server, when a template lists the
sshendpoint but the VHDX lacks it, is installed from Windows Update on first boot (several minutes). Prefer a template with OpenSSH preinstalled.The lease unattend sets
LocalAccountTokenFilterPolicy=1so the lease's local admin gets a full token over PowerShell Direct (needed for guest setup), and disables display/standby timeouts so screenshots stay live.
Configuration
See config.example.yaml. Key ideas:
Section | Purpose |
| listen address, |
| TTL bounds and default, per-user lease quota, reaper/reconcile intervals |
| one entry per hypervisor ( |
| catalog agents choose from: OS, arch, sources (host/node/ref), default size, credential mode, endpoints |
Credential modes:
Mode | Used for | Credentials |
| PVE Linux | random password + ed25519 key per lease (or user-chosen) |
| Hyper-V Windows | random admin password per lease (or user-chosen) |
| templates with a fixed account | template account; user-chosen account created after boot |
MCP tools
Tool | What it does |
| catalog with OS, arch, default resources |
| hosts, free memory, which templates they serve |
| lease a VM; blocks until reachable |
| state, IP, endpoints, credentials, connect hints |
| your active leases |
| extend |
| the VM's screen as a PNG image |
| end the lease now |
REST API
All endpoints except /healthz need Authorization: Bearer <api key>.
Method | Path | |
GET |
| catalog |
GET |
| capacity |
POST |
|
|
GET |
| your active leases ( |
GET |
| details ( |
POST |
|
|
GET |
| PNG of the console ( |
DELETE |
| destroy |
Errors are JSON: {"error": "no_capacity", "detail": "..."}.
User management
vmgw user add bob --max-leases 3
vmgw user list
vmgw user revoke bobDevelopment
uv run pytest # unit tests (fake backend, recorded hypervisor calls)
VMGW_LIVE=1 VMGW_LIVE_TEMPLATES=ubuntu-24.04,macos uv run pytest -m live -s # real hypervisors
VMGW_LIVE_USER='me:Secret-Pass1' ... # with custom credentialsSecurity notes
Run exactly one gateway per set of hosts: the reconciler deletes
vmgw-*VMs it has no lease for.Lease credentials are stored in the gateway's SQLite file; protect
data/.The PVE token can only manage VMs in pool
vmgwand clone templates invmgw-templates.The gateway trusts the LAN: SSH host keys are not verified unless
known_hostsis set per host.Hyper-V leases enable
LocalAccountTokenFilterPolicy(remote admin for local accounts) inside the guest; each lease has its own random password.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Secure Linux sandboxes for AI agents, as MCP tools.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables management of Proxmox VE virtual environments (VMs, containers, storage, snapshots, etc.) through natural language via MCP, with async task polling for reliable write operations.1653 npm1MIT
- AlicenseAqualityDmaintenanceEnables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.8MIT
- AlicenseAqualityFmaintenanceAn MCP server that lets AI agents manage virtual machines across local and cloud targets, with tools to create machines, run commands, transfer files, and clean up ephemeral instances via natural language.1115 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate disposable Linux computers via MCP, providing tools for shell, file read/write, directory listing, and port exposure. It also supports browser automation and integration with any MCP-compatible client.Apache 2.0