agentpc CLI

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

Command	Description
`agentpc create <image> [name]`	Create a VM from `ubuntu`, `windows` or a version such as `ubuntu-22.04`; fetches Ubuntu images if missing. `--memory` 2–64 GB (default 8 Windows, 4 Ubuntu) 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). The default name is `<os>-<n>`.
`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, and checkpoints.
`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

Command	Description
`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.
`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

Command	Description
`agentpc ssh <name> [command]`	Run a command (PowerShell on Windows, bash on Ubuntu), 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. `--list` shows a VM's forwards; `--rm <host-port>` stops one.

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.

Command	Description
`agentpc image pull <image>`	Download a published image, e.g. `ubuntu` or `ubuntu-22.04`. Ubuntu only; Windows can't be redistributed.
`agentpc image build <image> [--iso <path>]`	Build an image locally: Ubuntu ~3 min, Windows ~12 min plus the ISO download.
`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. Alias: `delete`.
`agentpc image snapshot <image>`	Recapture the snapshot VMs resume from (build and pull do this).

Setup

Command	Description
`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. Alias: `upgrade`.
`agentpc doctor`	Check prerequisites.
`agentpc clean [-n]`	Free disk space: downloaded ISOs and cloud images, and leftovers of interrupted builds or checkpoints. Never touches images or VMs.
`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