Vee

vee

A command-line VM manager built on QEMU/KVM, and on Apple's Virtualization.framework for macOS guests. Create, start, SSH into, and monitor virtual machines from a single lightweight tool — with GPU passthrough, virtiofs sharing, SPICE display, and SSH tunnelling wired in.

The backend is a per-VM choice, independent of the guest OS. Every guest runs on QEMU by default, with two exceptions on Apple Silicon hosts: macOS guests always run on Virtualization.framework (QEMU's experimental macOS machine does not work on current macOS hosts), and Linux guests can opt into it with --backend vz — which is the only way to give a Linux guest a host↔guest vsock device on a macOS host (see [docs/linux-vz.md](docs/linux-vz.md)).

vee create myvm    # create an Ubuntu 24.04 server VM
vee start myvm     # boot it (detached by default)
vee ssh myvm       # open a shell
vee stop myvm      # graceful shutdown

Quick start

make install       # build and install to ~/.vee/bin/vee
vee create myvm    # create an Ubuntu 24.04 server VM
vee start myvm     # boot — detached by default
vee ssh myvm       # open a shell
vee stop myvm      # graceful shutdown

> Prerequisites: KVM access, bridge networking, disk group membership, and OVMF firmware. See [docs/prerequisites.md](docs/prerequisites.md). > > macOS as a host (Apple Silicon): vee runs on Apple Silicon Macs, driving QEMU through Hypervisor.framework (HVF) with aarch64 guests. GPU acceleration is the weak spot — the published QEMU bundle is a plain-HVF build, because the pinned QEMU and the only macOS-patched virglrenderer cannot currently be compiled together. See [docs/macos.md](docs/macos.md) for setup, the per-guest GPU matrix, and limitations. > > macOS as a guest (Apple Silicon): vee can also restore and run a macOS VM — vee create mymac --template macos — on Apple's Virtualization.framework. This is a different thing from the note above, and it needs the vee-vz-helper binary, which ships beside vee in the darwin-arm64 release tarball; on an Apple Silicon checkout, make install builds and installs it alongside vee. Apple's licence permits macOS VMs only on Apple hardware and at most two at a time. See macOS guests or [docs/macos.md](docs/macos.md#macos-guests-virtualizationframework). > > Windows: vee also runs on Windows (amd64) via the Windows Hypervisor Platform (WHPX) with x86-64 guests. VFIO, virtiofs, vsock, bridge networking, and swtpm are Linux-only and degrade gracefully. See [docs/windows.md](docs/windows.md) for prerequisites and limitations.

Templates

Templates apply sane defaults (memory, CPUs, disks, networking, cloud-init) automatically.

| Template | Description | |----------|-------------| | ubuntu-server | Ubuntu 24.04 LTS · UEFI · user-mode NIC (default) | | devbox | Docker + zsh via cloud-init · --distro flag (ubuntu/arch/fedora) | | server | openssh + ufw + fail2ban via cloud-init · --distro flag | | desktop | GNOME + Mesa · accelerated virtio-gpu (virgl) · --distro flag (fedora/ubuntu) · Apple Silicon | | gaming-arch | Arch Linux + KDE Plasma + Steam · 16G / 8 CPUs · virgl or GPU passthrough | | gaming-bazzite | Bazzite (Fedora Atomic) gaming ISO · 16G / 8 CPUs · KDE Plasma | | gaming | Legacy alias for gaming-arch with passthrough | | passthrough | Raw NVMe boot + GPU passthrough · 8G / 6 CPUs · SPICE · virtiofs | | truenas | TrueNAS SCALE · 6G / 2 CPUs · AHCI OS disk · per-drive iothreads · bridge NIC · SPICE | | torrent | Lightweight 2G / 1 CPU · qbittorrent-nox via cloud-init · optional VPN kill-switch | | jellyfin | Jellyfin · NFS/SMB/host-dir/block/USB media · mDNS | | dns-sink | Alpine Linux · AdGuard Home DNS sinkhole · 512M / 1 CPU · LAN-wide ad and malware blocking · bridge NIC | | windows | Windows · UEFI · secure boot + TPM 2.0 on x8664 · arm64 (Apple Silicon) boots NVMe + ramfb with the hardware checks bypassed | | docker | Alpine Linux · Docker daemon on tcp://localhost:2375 | | github-runner | Self-hosted Actions runner · outbound HTTPS long-polling | | macos | macOS guest on Apple's Virtualization.framework · 8G / 4 CPUs · Apple Silicon hosts only · restores from an IPSW or imports a macosvm bundle |

vee create mynas --template truenas \
  --data-disk /dev/disk/by-id/ata-ST22000NM000C_ZXA0S3H6:EXOS22TB-A \
  --data-disk /dev/disk/by-id/ata-ST22000NM000C_ZXA0WD9J:EXOS22TB-B

vee pull ubuntu            # newest known Ubuntu cloud image
vee pull ubuntu 22.04      # a specific version
vee pull ubuntu-24.04      # same, as a single token
vee pull windows win10     # build the Windows 10 ISO (see below)
vee pull macos             # newest macOS restore image this host can install
vee pull --list            # list every supported distro and version

vee builds Windows install ISOs on demand — no manual ISO download required. It resolves the latest build via the UUP dump API, downloads the ESD packages directly from Microsoft's servers, and assembles a bootable UEFI ISO inside a throwaway container (wimlib + xorriso). The media matches the host: amd64 on x8664 hosts, arm64 on Apple Silicon and other arm64 hosts (mastered UEFI-only — ARM has no BIOS boot path).

vee pull windows win11             # Windows 11 24H2
vee pull windows win10             # Windows 10 22H2
vee pull windows server2025        # Windows Server 2025
vee create winvm --template windows   # pulls automatically if not cached

> Windows-guest status: both win10 (22H2) and win11 (24H2) install > end-to-end, booting to the desktop from the virtio system disk. 24H2 required > several workarounds (running Setup from a writable scratch disk, injecting > drivers via offlineServicing, and bundling winre.wim into install.wim). > See [docs/windows-guests.md](docs/windows-guests.md) for the ISO pipeline and > [docs/windows-24h2-install.md](docs/windows-24h2-install.md) for the full 24H2 > debugging writeup.

Requirements: nerdctl or docker on PATH (the ISO is assembled in a container; no host tooling is installed) and ~15 GB of free scratch space, which vee allocates next to the ISO cache (under ~/.vee/iso/) so the build works even when /tmp is a small RAM-backed tmpfs. The windows template additionally pulls the VirtIO driver ISO — on x8664 also WinFSP — so the guest gets paravirtualized disk and network out of the box (plus virtiofs on x8664; arm64 guests use an NVMe system disk and skip virtiofs until upstream ships a signed ARM64 viofs — see [docs/windows-guests.md → ARM64 guests](docs/windows-guests.md#arm64-guests)).

> Licensing: vee downloads Windows bits from Microsoft's own servers and > assembles the ISO locally — it never redistributes Windows. You still need a > valid Windows license key to activate the guest.

GPU passthrough

The gaming, gaming-arch, and passthrough templates use VFIO to wire a PCIe GPU directly into the VM — zero emulation, full metal.

Host requirements

1 · IOMMU — enable in kernel parameters:

intel_iommu=on iommu=pt   # Intel
amd_iommu=on iommu=pt     # AMD

2 · vfio-pci kernel modules — /etc/modules-load.d/vfio.conf:

vfio
vfio_iommu_type1
vfio_pci

3 · vfio group membership:

sudo usermod -aG vfio $USER

4 · Unlimited locked memory — VFIO DMA-maps all guest RAM:

sudo tee /etc/security/limits.d/vee-vfio.conf ` | Provision a new VM |
| `vee pull  [version]` | Download or build a base image into the cache (`vee pull macos` fetches a macOS restore image) |
| `vee start ` | Boot a VM (detached by default; `--recovery` boots into recoveryOS / the Linux rescue target where the backend supports it) |
| `vee stop ` | Graceful shutdown |
| `vee list` | List all VMs and status |
| `vee status ` | Show detailed status of a VM |
| `vee ssh ` | Open a shell |
| `vee ssh-share ` | Share host SSH agent into the VM via AF_VSOCK |
| `vee tunnel  [service]` | List VM services, or open/connect to one |
| `vee ports ` | List bound TCP ports and process names in a running VM |
| `vee ip ` | Show a VM's IP addresses (guest agent, or host lease/ARP tables by MAC) |
| `vee logs ` | Stream QEMU output, or the helper log for a macOS guest |
| `vee monitor ` | Real-time CPU / memory / disk / network stats |
| `vee qmp  ` | Send a QMP (QEMU Machine Protocol) command to a running VM |
| `vee screenshot  [file.png]` | Capture a running VM's display to a PNG file (works headless; QEMU backend) |
| `vee view ` | Open or connect to a VM's display (SPICE, GPU, or Screen Sharing for a macOS guest; `--native` opens the vz helper's own window — works in recoveryOS, at the login window, and during install) |
| `vee config ` | Edit a VM's configuration in an interactive TUI (`--ssh-port` changes the forwarded SSH port directly, live on a running VM) |
| `vee check ` | Run health checks on an installed VM |
| `vee network ` | Show firewall, VPN, DNS, route, and egress state of a running VM |
| `vee backup ` | Back up directories from a running VM |
| `vee autostart ` | Enable or disable autostart for a VM |
| `vee move  ` | Move a VM's boot disk to another directory |
| `vee resize  ` | Grow a VM's boot disk (absolute `60G` or relative `+40G`) |
| `vee delete ...` | Wipe one or more VMs and all their disks |
| `vee daemon` | Run the vee daemon (starts and watches autostart VMs) |
| `vee dashboard` | Start a web dashboard for all VMs |
| `vee mcp` | Run an MCP server over stdio so coding agents can drive vee |
| `vee gpu list` | List PCI GPUs and IOMMU groups |
| `vee gpu bind ` | Bind device to vfio-pci (requires root) |
| `vee gpu unbind ` | Release device back to host driver (requires root) |
| `vee gpu status ` | Pre-flight check for passthrough |
| `vee mirror start` | Start host-side pacman caching proxy (pacoloco) |
| `vee mirror status` | Show pacoloco unit state and cache size |
| `vee mirror stop` | Stop the pacoloco user unit |
| `vee mirror purge` | Delete all cached packages on disk |
| `vee runner key ` | Print a runner's GitHub SSH public key |
| `vee runner snapshot ` | Persist a runner's credentials to the host (encrypted) |
| `vee version` | Print version, commit, and build date |

Some of these are QEMU-only, because they are built on QEMU interfaces a macOS
guest has no equivalent of: `vee monitor`, `vee qmp` and the dashboard's live
stats need QMP, and `vee check` and `vee ports` need the QEMU guest agent. See
[macOS guests](https://vee.benehiko.com/getting-started/macos-guests/) for the
full matrix of what that backend supports.

## MCP server (coding agents)

`vee mcp` speaks the [Model Context Protocol](https://modelcontextprotocol.io)
over stdio, exposing vee as typed tools so coding agents can manage VMs
without parsing CLI output:

```sh
claude mcp add vee -- vee mcp    # Claude Code; other MCP clients work the same way

The MCP surface has feature parity with the CLI: every command either maps to tools (lifecycle, guest exec, ports, services, logs, QMP, stats, backups, images, GPU inspection, runner credentials, pacman mirror) or carries an explicit CLI-only exemption (interactive TUIs, root-mutating host operations). A test walks the command tree and fails the build when the two drift. A typical agent flow: vm_create {template: "devbox", start: true} → vm_exec {command: "docker run --rm alpine echo ok"} → vm_delete. See [docs/mcp.md](docs/mcp.md) for the full tool reference.

Shell completion

source --.tar.gz` and an unversioned `vee--.tar.gz`,
so install docs can use a stable `releases/latest/download/…` URL. A GitHub
Release is published whose body lists the commits since the previous tag.
Tags containing a hyphen (e.g. `v0.4.0-rc1`) are marked as pre-releases.

The `darwin/arm64` archive additionally contains `vee-vz-helper`, built with cgo
and ad-hoc codesigned in the workflow; the release fails if the
`com.apple.security.virtualization` entitlement did not land, since macOS would
refuse to run the helper without it. When `docs/release-notes/.md` exists it
is prepended to the release body, so a release whose story is larger than its
commit subjects can lead with the story.

On Windows, VFIO passthrough, virtiofs, vsock, swtpm, bridge networking, and the
systemd daemon are Linux-only and degrade gracefully; the binary runs x86-64
guests under WHPX. See [docs/windows.md](docs/windows.md).

### Installing a release

Download the `.tar.gz` for your platform from the
[Releases page](https://github.com/Benehiko/vee/releases), verify it against the
matching `.sha256`, extract the `vee` binary onto your `PATH`, and install the
host QEMU packages. Full step-by-step instructions (Linux, macOS, Windows) plus
how to run vee as a daemon are in the
[Installation guide](https://vee.benehiko.com/getting-started/installation/).

Apple Silicon users who want macOS guests should install the tarball's second
binary, `vee-vz-helper`, into the same directory as `vee` (vee also accepts an
explicit path in `$VEE_VZ_HELPER`, and falls back to `~/.vee/bin` and `$PATH`).
A browser download arrives quarantined, which Gatekeeper would refuse to run;
vee clears that flag itself every time it resolves the helper, re-signing only if
the signature is missing the entitlement. No other platform ships the helper, and
no other guest needs it.

## Docs

The full documentation site is published at ****. Deep-dive
docs also live in this repo:

- [docs/prerequisites.md](docs/prerequisites.md) — system setup, groups, bridge networking, OVMF
- [docs/macos.md](docs/macos.md) — macOS on Apple Silicon: HVF host support, the per-guest GPU matrix, and macOS guests on Virtualization.framework
- [docs/linux-vz.md](docs/linux-vz.md) — Linux guests on Virtualization.framework (`--backend vz`): native vsock on macOS hosts, EFI or direct-kernel boot, raw disks
- [docs/windows.md](docs/windows.md) — Windows (WHPX) host support, feature matrix, and the nested-virtualization limitation
- [docs/windows-guests.md](docs/windows-guests.md) — the on-demand Windows guest ISO build pipeline
- [docs/windows-24h2-install.md](docs/windows-24h2-install.md) — full writeup of the Windows 11 24H2 install debugging
- [docs/qmp.md](docs/qmp.md) — `vee qmp`, `v

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Benehiko](https://github.com/Benehiko)
- **Source:** [Benehiko/vee](https://github.com/Benehiko/vee)
- **License:** MIT

Install and usage instructions live in the source repository linked above.