Home / Documentation

Windows and Linux VM CLI reference

Everything agents do over MCP, you can do from Terminal with agentpc, plus image builds, setup and updates.

Quick start

$ agentpc create ubuntu           # first run downloads ~1.2 GB; then ~1 s per VM
$ agentpc ssh ubuntu-1 uname -a
$ agentpc screenshot ubuntu-1 shot.png
$ agentpc info ubuntu-1           # viewer URL to watch the desktop
$ agentpc reset ubuntu-1          # back to a clean install

Windows images can't be redistributed, so each Mac builds its own once, from Microsoft's official Windows 11 ARM64 ISO (7.3 GB, checksum-verified): 

$ agentpc image build windows     # once: download + ~12 min install; or --iso <path>
$ agentpc create windows          # ~4 s per VM

Commands that act on VMs take several names (agentpc stop a b), check them all before doing anything, and carry on past a failure (exit status 1 if any failed). Every command has --help.

VMs

CommandDescription
agentpc create <image> [name] Create a VM from ubuntu, windows, arch or a version such as ubuntu-22.04, or ubuntu-x86apps / arch-x86apps for x86_64 and i386 Linux programs; fetches Ubuntu and Arch images if missing. --memory 2–64 GB (default 8 Windows, 4 Ubuntu and Arch) and --cpus 1–16 (default 4); a non-default size boots cold instead of resuming. --offline: no internet and no access to this Mac (SSH, the viewer and forwarded ports still work). --open (alias --open-in-browser) opens the ready VM’s viewer in the Mac’s default browser (off by default). Browser-launch failure warns without failing creation. The default name is <os>-<n>; a name is up to 64 letters, digits, . - _. --from <vm>/<label> creates it from a checkpoint of another VM instead (the image is then optional and must be the source's; --name names it): a copy of the checkpoint's disk, booted cold; its memory, port forwards and job records are not carried over.
agentpc list [--json] VMs and images. --json gives the same data as the MCP list_vms tool. Alias: ls.
agentpc info <name> Viewer URL (with the VNC password), SSH and VNC details, checkpoints, and on x86apps VMs how x86 programs run (x86 programs: FEX, hardware|emulated TSO).
agentpc start <name>… | --all Boot stopped VMs.
agentpc stop <name>… | --all Shut VMs down cleanly; disks are kept.
agentpc reset <name>… Discard all changes: back to a fresh copy of the image.
agentpc rm <name>… Delete VMs with their disks and checkpoints. Alias: delete.

Checkpoints

CommandDescription
agentpc checkpoint <name> <label> Save a VM's disk and memory under a label (letters, digits, . - _). A running VM pauses for a few seconds. -d / --delete deletes the checkpoint instead. A running VM's guest first writes its pending data to disk; if it can't within ~10 s the reply says "not flushed".
agentpc restore <name> <label> Put a VM back exactly as it was at a checkpoint; it resumes in seconds. 
$ agentpc checkpoint windows-1 before-installer
$ agentpc cp setup.msi windows-1:Downloads/
$ agentpc ssh windows-1                        # run the installer, poke around
$ agentpc restore windows-1 before-installer   # undo it all in seconds

A checkpoint of a running VM takes disk space about equal to the memory in use (3–4 GB for Windows). The disk itself is an APFS copy-on-write clone, so it costs nothing until the VM writes more.

Shell, files and ports

CommandDescription
agentpc ssh <name> [command] Run a command (PowerShell on Windows, bash on Ubuntu and Arch), or open an interactive shell with no command.
agentpc screenshot <name> [file] Save a PNG screenshot from the hypervisor. Without a file, it goes to screen.png in the VM's directory.
agentpc cp <src> <dst> Copy files or folders. The VM side is <name>:<path>, e.g. agentpc cp app.msi windows-1:Downloads/.
agentpc forward <name> <guest-port> [host-port] Forward 127.0.0.1:<host-port> to a port in a running VM over SSH. --udp forwards UDP instead (to a guest server on 0.0.0.0). --list shows a VM's forwards; --rm <host-port> stops one (add --udp/--tcp to pick a protocol).

Images

An image is a read-only disk with the OS, desktop and agent tools installed. Images are named <os>-<version> and can be installed side by side. See the guide for the versions available.

CommandDescription
agentpc image pull <image> Download a published image, e.g. ubuntu, ubuntu-22.04, ubuntu-x86apps, arch or arch-x86apps. Dated builds (ubuntu-24.04-YYYYMMDD, arch-rolling-YYYYMMDD, …-x86apps-YYYYMMDD) can only be pulled. Pulling again after a failure resumes, reusing the parts already verified. Windows can't be redistributed.
agentpc image build <image> [--iso <path>] Build an image locally: Ubuntu ~3 min, Arch ~6 min (in an Ubuntu helper VM), ubuntu-x86apps ~8 min, arch-x86apps ~10 min, Windows ~12 min plus the ISO download. Refuses while VMs of that image exist or a running build uses it.
agentpc image ls List local images with their OS versions. Alias: list.
agentpc image info <image> Everything recorded about an image: OS version, edition, build, source and tool versions.
agentpc image rm <image>… Delete local images. Refuses while VMs of that image exist, a running build uses it (an Arch build runs in a clone of the Ubuntu image), or a pull or snapshot of it runs. Alias: delete.
agentpc image snapshot <image> Apply this agentpc's guest setup to the image and recapture the snapshot VMs resume from (build and pull do this); its VMs must be deleted first.

Setup

CommandDescription
agentpc mcp Run the MCP server on stdio (what agents launch).
agentpc mcp-install [clients…] Register the MCP server with agents. mcp-uninstall removes it.
agentpc update [--check] Update to the latest release, checksum-verified; images and VMs are kept. agentpc list then marks images whose guest setup is older, and agentpc image snapshot <image> refreshes one. Alias: upgrade. If the binary's directory isn't writable, it suggests sudo agentpc update or reinstalling with AGENTPC_INSTALL_DIR.
agentpc doctor Check prerequisites, with the macOS and QEMU versions (warns below macOS 15, where x86apps VMs get emulated TSO, and below QEMU 9.0).
agentpc clean [-n] Free disk space: downloads fetched again when needed (ISOs, cloud images, the ~830 MB Arch Linux ARM tarball), leftovers of interrupted builds, pulls or checkpoints, and other versions' TSO libraries. Never touches images or VMs, and keeps what a running build, pull or push uses.
agentpc uninstall [--keep-data] [-y] Stop all VMs, unregister the MCP server, and delete ~/.agentpc and the binary.

Completions

Tab completion for bash, zsh, fish, elvish or PowerShell:

$ agentpc completions zsh > ~/.zfunc/_agentpc