Docker-like micro-VMs for Apple Silicon, with a GPU inside the container,
a desktop when you want one, and MCP for AI agents.
Quick start · Documentation · Known issues · Architecture
Docker on macOS gives containers no GPU. VeynodeVM runs each container as its own micro-VM, on QEMU/HVF with virtio-gpu (OpenGL/GLES through virgl, Vulkan through Venus → MoltenVK → Metal) or on Apple Virtualization. A control daemon owns every VM and serves the CLI, a web UI and MCP.
- 🐳 Docker-like CLI. OCI pull,
run/exec/logs/stop/rm, interactive-itandattach,-p/-v, plus a shared docker engine for thedockerCLI, compose andbuild. - 🎮 GPU in the container.
--gpus virgl(OpenGL 2.1 / GLES 3.0) and--gpus venus(Vulkan 1.3 on Metal). On an XFCE desktop, OpenGL runs through Zink on Venus and SuperTuxKart renders at about 115 FPS. - 🖥️ Desktops. A native AppKit window and a low-latency browser desktop for QEMU, Apple Virtualization Linux and macOS containers.
- 🍎 macOS containers. Tart-compatible OCI images with the paravirtualized Metal GPU; a game-like Metal frame renders at 99% of the host's rate.
- 🐧 Full Linux and Windows machines. Ubuntu and Fedora install unattended from their own ISOs; Windows 11 ARM64 installs from yours, with experimental D3D11 on Metal.
- 🤖 MCP for AI agents. Screenshots, input, screen waits, OCR with clickable boxes, windows, apps and the accessibility tree; macOS guests need no Screen Recording or Accessibility grants.
- ⏪ Checkpoints and forks. APFS-clone checkpoints with memory, rollback with processes running, and forks with fresh identities.
- 🌐 Web UI. Containers, a terminal and the desktop in the browser.
Needs an Apple Silicon Mac with macOS 14+ (Venus needs macOS 26+), the Swift command-line tools and brew install rust go node qemu squashfs.
cargo build -p veynodevm -p vm-control && ./scripts/build-native.sh
python3 guest/kernel/build.py # pinned kernel + initramfs with the agent as PID 1
python3 scripts/install-dev-runtime.py --dns 1.1.1.1
veynodevm daemon start # launchd user agentveynodevm run --rm alpine echo hi # one micro-VM per container
veynodevm run -d -p 8080:80 --name web nginx:alpine
veynodevm exec web nginx -v
veynodevm run -d --desktop --name desk veynodevm/alpine-desktop
veynodevm desktop desk # native window
veynodevm ui # web UI in the browser
veynodevm mcp --lifecycle # stdio MCP server for agentsGPU containers need the QEMU runtime: see building the GPU runtime. Every other command is in the usage guide.
| Guide | |
|---|---|
| Usage | Containers, the docker engine, desktops, GPUs, macOS containers, checkpoints, MCP |
| Linux machines | Full distributions booted through UEFI from their ISOs |
| Windows 11 ARM64 | Unattended install from your own ISO |
| Building and checking | Checks, release directory, desktop helpers, GPU runtime |
| Low-level control path | Driving vm-control directly |
| Reference | |
|---|---|
| Product spec | What VeynodeVM is for, and its release gates |
| Architecture | Daemon, workers, guest agent and where capabilities live |
| Local API 1 | The daemon's socket protocol |
| Computer use | MCP desktop tools |
| Security | Trust boundaries |
| Known issues | What is verified, and the limits |
| Decisions | Architecture decision records |
Experiments, benchmarks and validation evidence from the earlier phase are kept in a separate, unpublished archive repository. Paths written as vm-archive/... in the docs, and the evidence values in capability reports, name records in that archive.
The control daemon owns every record and serves local API 1 on a Unix socket; the CLI, web UI and MCP servers are its clients. Each VM runs in its own worker: vm-qemu for QEMU/HVF with virgl or Venus, vm-apple for Apple Virtualization. Inside Linux micro-VMs, the Go guest agent is PID 1.
| Component | Path | State |
|---|---|---|
veynodevm CLI |
crates/cli |
implemented |
| Local API 1 | crates/api, docs/api.md |
implemented |
| Control daemon, services, MCP server | crates/control |
implemented |
| MCP HTTPS endpoint | crates/mcp |
implemented |
| OCI registry, blob store, layers | crates/oci |
implemented |
| QEMU/HVF worker (virgl, Venus) | crates/control/src/bin/vm-qemu.rs |
implemented (Venus experimental) |
| Apple Virtualization worker | native/worker |
implemented (2D display, no GPU) |
| Guest kernel, initramfs and agent | guest/kernel, guest/veynode-agent |
implemented |
| Official desktop and GPU images | guest/images |
verified on VZ, virgl and Venus |
| Shared docker engine | crates/control/src/services/engine.rs |
implemented |
| Full Linux and Windows machines | crates/control/src/services/machines.rs |
implemented |
| macOS containers | crates/oci/src/tart.rs, crates/control/src/services/macos.rs |
implemented |
| Web UI | web/ |
implemented |
| Native desktop console | native/console |
implemented |
| Console broker, H.264/HEVC WebRTC | crates/media-local, browser/ |
localhost only |
| Device pairing and signed sessions | crates/session-auth |
localhost only |
| GPU runtime (UTM QEMU, virglrenderer, SPICE) | runtime/ |
development only |
./scripts/check.sh # native build, cargo fmt/build/test/clippy, go, python, browser and web tests
scripts/check-changed.py # only the checks the files changed against main needSee building and checking for the release directory, the desktop helpers and the GPU runtime.
VeynodeVM is licensed under the Apache License 2.0. The code that runs inside the GPU runtime's QEMU or SPICE process (the loaders, spice-scanout-generation.c and the runtime patches) is licensed under GPL-2.0-or-later, and the DXMT patch under LGPL-2.1-or-later, as decision 0026 records. NOTICE lists those files and the third-party code in this repository. The GPU runtime itself is not part of this repository and keeps its own licenses.