agentpc

Instant, resettable Windows and Ubuntu desktops for AI agents, on your Mac.

agentpc gives AI agents (Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, VS Code, or any MCP client) real desktop computers to work in: create a VM in seconds, let the agent click, type, take screenshots and run commands, then reset it to a clean state. It is a single Rust binary that runs VMs with QEMU on Apple's hypervisor and serves them to agents over MCP.

Contents

• Features

• Requirements

• Installation

• Quick start

• Using it with AI agents

• CLI reference

• Images

• Configuration

• How it works

• Troubleshooting & guest tips

• Uninstalling

• Security

• Development

• License

Related MCP server: sandbox-mcp

Features

• Instant VMs. New VMs resume from a saved snapshot of a running desktop: ready in ~1 s (Ubuntu) or ~4 s (Windows). reset returns a VM to a clean state just as fast.

• Checkpoints. Save a running VM (disk and memory) before a risky step and return to that exact state in seconds.

• Real desktops. Windows 11 (ARM) and Ubuntu 24.04 or another release (XFCE), each with a desktop-control server agents can drive: Windows-MCP and cua-driver.

• One MCP server for everything. Agents create, drive, screenshot and delete VMs themselves. Works with any MCP client; agentpc mcp-install sets up the popular ones.

• Shell and screen access. Run PowerShell or bash over SSH; take PNG screenshots straight from the hypervisor in ~40 ms, even while a guest is booting or hung.

• Files and ports. Copy files and folders between your Mac and a VM, and reach servers running inside a VM from your Mac.

• Agent-ready guests. 1280x800 desktops with a browser (Edge on Windows, Chrome on Ubuntu) and the pop-ups, update restarts and background jobs that interrupt unattended work turned off.

• Watch along. Every VM has a browser viewer, so you can see what the agent is doing.

• Any version, side by side. Run Ubuntu 22.04, 24.04 and 26.04, or several Windows 11 releases, at the same time. Each image records its OS version, source and build date.

• Local and private. Everything runs on your Mac and listens on 127.0.0.1 only.

Requirements

Installation

curl -fsSL https://raw.githubusercontent.com/pawanpaudel93/agentpc/main/install.sh | sh

The installer:

1. downloads the latest release and verifies its checksum,

2. installs agentpc to ~/.local/bin (no sudo) and adds it to your PATH,

3. installs QEMU with Homebrew if it's missing (installing Homebrew first if needed, which asks for your password once),

4. registers the MCP server with the agents it finds (agentpc mcp-install),

5. checks everything with agentpc doctor.

Run it again to upgrade. Installer options:

To build from source instead, see Development.

Quick start

Ubuntu:

agentpc create ubuntu        # first run: downloads (~1.2 GB) and prepares the image; then ~1 s per VM

Windows: Microsoft's license doesn't allow redistributing Windows images, so each Mac builds its own once. agentpc downloads the official Windows 11 ARM64 ISO from Microsoft (7.3 GB, checksum-verified) unless you already have one:

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

Then ask your agent something like:

• "Create an Ubuntu VM, open a terminal and run uname -a."

• "Reset ubuntu-1 and check that my install script works on a clean machine."

• "Open Notepad on windows-1, type a short note and show me a screenshot."

To watch a VM yourself, open the viewer URL printed by agentpc info <name>.

Using it with AI agents

agentpc is an MCP server (agentpc mcp, stdio). One server handles every VM.

Claude plugin

In Claude Code, install the agentpc plugin. It bundles the MCP server with a skill that teaches Claude when and how to use the VMs:

/plugin marketplace add pawanpaudel93/agentpc
/plugin install agentpc@agentpc

The plugin runs the installed agentpc binary, so install that first (see Installation). When the plugin is installed it already registers the MCP server for Claude Code, so agentpc mcp-install skips Claude Code to avoid a duplicate.

Other agents

Register it with every supported agent that's installed (the installer does this):

agentpc mcp-install                  # or pick: agentpc mcp-install claude claude-desktop codex

Supported: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI and VS Code (restart Claude Desktop after registering). For any other MCP client, add:

{
  "mcpServers": {
    "agentpc": { "command": "agentpc", "args": ["mcp"] }
  }
}

This repository also contains project-level configs (.mcp.json, .codex/config.toml, .cursor/mcp.json, .gemini/settings.json, .vscode/mcp.json), so agents opened in a clone pick the server up automatically.

Tools

VMs an MCP session created or started are stopped (never deleted) when the session ends, unless AGENTPC_KEEP_RUNNING=1.

AGENTS.md has usage tips for agents.

CLI reference

VMs

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.

Image commands

Setup

Images

An image is a read-only disk with the OS, desktop and agent tools installed. Every VM is a copy-on-write clone of an image, so a VM starts from a clean install and costs only a few MB.

Images are named <os>-<version>, and several can be installed side by side; each VM remembers which one it came from. A bare ubuntu means ubuntu-24.04, and a bare windows (or windows-11) means windows-11-25h2. To save a 12-minute build, create and image info fall back to your newest installed Windows 11 image if 25H2 isn't built. Pin the full name when the release matters, e.g. in test harnesses.

Only ARM64 Windows runs at native speed on Apple Silicon, so x64-only releases aren't offered, and Windows 10's ARM64 build hangs at boot on Apple Silicon, so Windows 11 is the minimum. The unattended install uses the Home/Pro setup key, so Enterprise and LTSC ISOs aren't supported. An ISO in ~/Downloads is used when its file name shows the release being built; --iso with a release name must match it too (a 24H2 ISO can't become windows-11-25h2). Windows runs unactivated (a watermark, nothing else); activate it with your own key if you need to.

Images are clean installs, like a customer's new PC: Windows has no Visual C++ redistributable, no .NET (only the built-in .NET Framework 4.8.1) and no PowerShell 7. A program that runs on your machine but fails in a VM with a missing VCRUNTIME140.dll or similar is missing a dependency its installer should provide. Microsoft's evaluation ISOs aren't offered: they install already expired and shut down every hour.

Microsoft serves only its current ARM64 ISOs; the older ones download from archive mirrors (archive.org, bobpony.com). Every ISO is checked against a pinned SHA-256, so a mirror can't substitute a modified file, and kept in ~/.agentpc/cache. All are en-us; for another language, download it yourself and pass --iso.

agentpc image build ubuntu-22.04     # ~3 min
agentpc create ubuntu-22.04          # VMs from different versions run side by side

Each image records what it is (agentpc image info <image>):

{
  "os": "windows",
  "version": "Windows 11 Pro 25H2 (build 26200.6584)",
  "version_id": "11-25H2",
  "arch": "arm64",
  "base": "Windows 11 25H2 (Home/Pro) ISO, ARM64, en-us",
  "built": "20260927",
  "agentpc": "0.1.0",
  "desktop_server": "Windows-MCP 0.8.5",
  "iso_sha256": "32cde007…"
}

Published images live in one package, ghcr.io/pawanpaudel93/agentpc, tagged by image name. Only Ubuntu is published (Windows images can't be redistributed):

Configuration

Each VM gets its own ports on 127.0.0.1, derived from its slot number n (an existing VM moves to its new ports the next time it starts):

The guest login is agent / agent. Each VM also has its own VNC password (see Security).

How it works

• Hypervisor. VMs run in QEMU with Apple's Hypervisor.framework (HVF), natively on Apple Silicon, with nothing else in between.

• Instant start. After building or downloading an image, agentpc boots it once, waits until the desktop and its control server are running, and saves the VM's memory. New VMs resume from that saved state instead of booting (~1 s / ~4 s instead of ~14 s / ~25 s). A start after stop is a normal boot; reset resumes a fresh copy again.

• Checkpoints. A checkpoint pauses the VM for a few seconds, writes its memory to a file and clones its disk (an APFS copy-on-write clone, so it costs nothing until the VM writes more). Restoring resumes from them like a new VM does. Each checkpoint of a running VM takes disk space about equal to the memory in use (3–4 GB for Windows); agentpc checkpoint <name> <label> --delete removes one, and deleting the VM removes all of them.

• Snapshots stay local. A memory snapshot depends on the Mac's chip and QEMU version, so only the disk is published; the snapshot is recaptured after each pull (about a minute). Each snapshot records the QEMU machine type, so it still resumes after a QEMU upgrade.

• Robustness. create checks free disk and RAM up front and checkpoint checks disk; restore is atomic (a failed one leaves the VM as it was) and resumes a VM that was left paused; operations on one VM are serialized, and a stale pid file from a crash is detected rather than trusted. The guest clock follows the Mac's time zone. SSH keepalives hold long calls open, a desktop tool call gives up after 120 s, and a viewer that won't start no longer fails a VM start. The browser viewer (noVNC) is downloaded against a pinned checksum.

• Image distribution. Ubuntu images are OCI artifacts on GitHub Container Registry: a compressed qcow2 split into 64 MB parts, downloaded in parallel and checksum-verified.

• Windows build. agentpc writes a small setup disk next to the ISO: an unattended-install answer file (adapted from dockur/windows-arm), Red Hat's ARM64 virtio drivers, and a first-logon script that installs OpenSSH and Windows-MCP. Windows Setup then runs in QEMU with no clicks.

• Ubuntu build. The official cloud image is provisioned with cloud-init: XFCE on X11, auto-login, and cua-driver (pinned, like Windows-MCP, so tool names match these docs). cloud-init is then disabled so clones don't re-provision.

• Agent-ready guests. Each time a snapshot is captured, a prepare script turns off what interrupts unattended work (Windows SmartScreen, updates, first-run and tip pop-ups; Ubuntu's background apt jobs) and installs Google Chrome on Ubuntu for cua-driver's browser tools.

Troubleshooting & guest tips

• Check the setup: agentpc doctor.

• See the screen: agentpc screenshot <name>, or open the viewer URL from agentpc info <name>.

• Logs for each VM are in ~/.agentpc/instances/<name>/: qemu.log (QEMU errors) and serial.log (guest console).

• A VM is in a bad state: agentpc reset <name>.

• image build/pull/rm refuses: VMs still depend on that image; agentpc rm them first.

Networking

Each VM sits behind QEMU's user-mode NAT, so VMs are isolated from each other but share the Mac's network (a VPN or proxy configured on the Mac applies to a VM's outbound traffic).

• Reach a server in a VM from the Mac: agentpc forward <name> <guest-port> [host-port] (MCP: forward_port), then connect to 127.0.0.1:<host-port>. It tunnels over SSH, so it reaches a server bound to the guest's own 127.0.0.1 and the Windows firewall doesn't apply. A forward lasts until the VM stops or you remove it (--rm <host-port> / delete_forward); --list (MCP: list_forwards) shows a VM's forwards.

• Reach the Mac from a guest: 10.0.2.2 is the Mac host — the NAT maps it to the Mac's loopback, so a dev server listening on 127.0.0.1 or 0.0.0.0 is reachable at 10.0.2.2:<port> from inside the VM.

• VM to VM: there's no direct route. Forward the server VM's port to the Mac (forward_port(B, guest_port, host_port)), then from the other VM connect to 10.0.2.2:<host_port>.

• Offline VMs (--offline / offline: true) can't reach 10.0.2.2 or the internet, but ports you forward from the Mac still reach them.

• Corporate proxy / CA: a guest inherits no proxy settings from the Mac. Set HTTP_PROXY and HTTPS_PROXY inside the guest, and import your corporate root CA with Import-Certificate (Windows) or update-ca-certificates (Ubuntu).

Guest reboots

Rebooting a guest (a Windows Update install, some installers) drops the SSH connection. Call start_vm on the same VM — it waits until the desktop is ready again even when the VM is already running — or simply retry run_command once it's back.

Windows guest tips

• GUI installers return immediately. Run them silently and wait for the process: Start-Process installer.exe -ArgumentList '/S' -Wait -PassThru (the switch varies: /S, /silent, /quiet), then check its ExitCode. A run_command process ends when the command returns, so start servers and GUI apps with background: true.

• Windows Update is disabled in the image (the wuauserv service is stopped and set to Disabled, and the NoAutoUpdate policy is set) so updates never interrupt a task. This also blocks optional features that fetch from Windows Update — DISM /online (e.g. .NET 3.5) and Add-WindowsCapability (RSAT, language packs; OpenSSH is already installed). To use one, re-enable it temporarily and set it back afterwards:

  Set-Service wuauserv -StartupType Manual; Start-Service wuauserv
  # … Add-WindowsCapability / DISM …
  Stop-Service wuauserv; Set-Service wuauserv -StartupType Disabled

• Defender real-time protection is on. agentpc only disables SmartScreen, not Defender, so Defender may quarantine a freshly built or unsigned test binary. Exclude your work directory with Add-MpPreference -ExclusionPath C:\work, or turn real-time monitoring off with Set-MpPreference -DisableRealtimeMonitoring $true (Tamper Protection may block the latter).

Hardware limits

Guests have a fixed 1280x800 display, a 2D-only virtio GPU (no 3D/GPU acceleration; WebGL is software-rendered or unavailable), and no audio device.

Uninstalling

agentpc uninstall            # asks first; -y skips the prompt

This stops all VMs, removes the MCP server from every agent mcp-install registered it with, deletes ~/.agentpc (images, VMs, checkpoints and keys; --keep-data keeps them) and the agentpc binary. It leaves shared things alone and lists them: the PATH line the installer added (~/.local/bin is used by other tools too), QEMU (brew uninstall qemu if nothing else needs it) and the Claude plugin (/plugin uninstall agentpc@agentpc).

To only reclaim disk space, agentpc clean deletes what can be downloaded again, and agentpc image rm <image> deletes an image you no longer use.

Security

• Everything listens on 127.0.0.1 only.

• The desktop-control servers inside the VMs are unauthenticated; any process on your Mac can reach them.

• Each VM has its own VNC password (vnc-pass, mode 0600, in its instance dir). The viewer URL from agentpc info <name> carries it (&password=…) so the browser viewer connects without a prompt; a native VNC client (vnc://127.0.0.1:<port>) asks for it — copy it from that URL or read ~/.agentpc/instances/<name>/vnc-pass.

• Guests use the fixed login agent / agent.

• To keep agents unblocked, Windows VMs have UAC prompts, SmartScreen and Windows Update turned off. Don't use them for anything that needs those protections.

• VMs can reach the internet and, through its gateway 10.0.2.2, services on your Mac. Create a VM with --offline (offline: true in create_vm) to cut both off, e.g. for untrusted software; SSH, the viewer and forwarded ports keep working.

• The MCP tools carry annotations: list_vms, take_screenshot and list_desktop_tools are read-only, and tools that discard or overwrite state (including download_file, which writes to your Mac) are marked destructive, so clients can auto-approve or confirm accordingly.

• Treat VMs as throwaway sandboxes, not as a place for secrets.

Development

cargo build --release                  # target/release/agentpc
cargo clippy --all-targets -- -D warnings
cargo test

Guest provisioning files in guests/ are embedded into the binary. AGENTS.md describes the code layout for contributors and coding agents.

1. On an up-to-date, clean main, run scripts/release.sh X.Y.Z (needs gh logged in, Node for npx, and jq). It sets the version everywhere (skipped when Cargo.toml is already at X.Y.Z), runs the CI checks, builds dist/ (binary tarball, MCP bundle agentpc-X.Y.Z.mcpb, their .sha256 files, a filled-in server.json and NOTES.md, the release notes grouped from the Conventional Commit subjects since the last tag), then asks before it commits chore: release vX.Y.Z, tags vX.Y.Z, pushes main and the tag, and creates the GitHub Release. --dry-run stops after building dist/.

2. Publish the Ubuntu image: agentpc image build ubuntu, then log oras in with a token that can write packages (gh auth refresh -s write:packages, then gh auth token | oras login ghcr.io -u <user> --password-stdin) and run agentpc image push ubuntu. It uploads 64 MB parts, retries failures and links the package to this repo; make the package public once in its settings.

3. Publish to the MCP Registry: brew install mcp-publisher, mcp-publisher login github, then mcp-publisher publish dist/server.json.

License

MIT © 2026 Pawan Paudel