WendyOS in a Virtual Machine

What this is for

wendy vm runs a real WendyOS ARM64 image on your own machine. It is the same image a physical device runs — same agent, same containerd, same entitlements — so you can build and deploy apps before you have hardware on your desk, or alongside it.

On an Apple Silicon Mac this is also the fastest development loop WendyOS has. wendy run targets linux/arm64, and an ARM64 guest on an ARM64 host builds natively, with none of the emulation an x86 machine pays when it cross-builds for a device.

The VM has no camera, microphone, speaker, Bluetooth adapter, GPU, GPIO or USB devices, and it does not do OTA updates. Anything under Hardware Access needs a real device. The VM is for the software half of your project.

What you'll need

QEMU, plus its ARM64 UEFI firmware:

brew install qemu

sudo apt install qemu-system-arm qemu-efi-aarch64

Published VM images are not available yet. Until they are, build one from WendyOS-Builder with make setup BOARD=qemu-arm64 && make build MACHINE=qemuarm64-wendyos, and pass it with --image wherever this guide omits the flag.

Once images are published, that is the only prerequisite: wendy vm create downloads the image itself the first time you need it and reuses that download for every VM afterwards.

Create and start a VM

Create it

wendy vm create dev

The published image is downloaded and unpacked straight into the VM's disk. It is cached compressed, so a second VM starts from the cache rather than the network, and the raw multi-gigabyte image is never written twice. --disk sets the disk size and WendyOS expands /data into the extra room on first boot; the disk is sparse, so a 16 GiB VM only occupies what it uses. Container images live on the root filesystem rather than /data, so a bigger disk does not give wendy run more room.

To pin a version, or to run a VM from an image you built yourself:

wendy vm create dev --version 0.19.0
wendy vm create dev --image ./wendyos-image-qemuarm64-wendyos.rootfs.wic

Start it

wendy vm start dev

This attaches you to the VM's console. Press Ctrl-A then X to power it off.

Talk to it

In another terminal:

wendy --device 127.0.0.1:50051 device info

To avoid repeating the address:

wendy device set-default 127.0.0.1:50051
wendy run

Trying a change before it merges

Every pull request to WendyOS-Builder builds a VM image, so a change can be run without hardware and without waiting for a release:

wendy vm create review --pr 1234
wendy vm start review

--pr takes the pull request number and stands in for the version: a PR publishes exactly one build, so it cannot be combined with --version, --nightly or --image.

Networking, and why `wendy discover` may not see it

wendy vm start offers two networks, and the choice decides whether the VM can be discovered.

`--net`	Setup needed	`wendy discover` finds it
`user` (default)	none	No — reach it at `127.0.0.1:50051`
`shared`	one-time `socket_vmnet` install	Yes

The default forwards the agent's port to your machine and needs no privileges, but it cannot carry the multicast that mDNS is built on — so the VM is reachable by address and invisible to discovery. This is a property of the network, not a fault in the VM, and wendy vm start says so when it launches.

For discovery, put the VM on a network your machine shares with it:

brew install socket_vmnet
sudo brew services start socket_vmnet
wendy vm start dev --net shared

On macOS 15 and later the first wendy discover may ask for Local Network permission. Discovery cannot see anything until you allow it.

If port 50051 is taken

The agent's port is often already in use on a development machine. Move the host side of the forward:

wendy vm start dev --port 50151
wendy --device 127.0.0.1:50151 device info

Managing VMs

wendy vm list          # every VM on this machine
wendy vm rm dev        # delete a VM and its disk

VMs live in ~/.wendy/vms/<name>/. Removing one deletes its disk, which cannot be undone — but the image you created it from is untouched, so you can always make a fresh one.

Options

Flag	Default	Purpose
`--image`	—	Create from a local `.wic` instead of downloading
`--version`	latest	Version to download
`--nightly`	off	Download a nightly rather than a release
`--disk`	`16`	Disk size in GiB
`--net`	`user`	`user` or `shared` — see above
`--port`	`50051`	Host port forwarded to the agent
`--memory`	`4096`	Guest memory in MiB
`--cpus`	`4`	Guest CPU count

Troubleshooting

no ARM64 UEFI firmware found — QEMU is installed but its firmware is not. Reinstall it with the command under What you'll need; the error lists every path that was searched.

host port already in use — something already holds 50051. Use --port.

socket_vmnet helper not found — --net shared needs the helper installed and running. Install it as above, or drop back to --net user and reach the VM by address.

It boots slowly. On a Mac without Apple Silicon, or on an x86 PC, the guest is emulated rather than accelerated, because the guest is ARM64 and the host is not. It still works; it is just slower. wendy vm start prints which mode it chose.

Install Wendy

Install Wendy CLI

Install `wendy-agent`