Guide

Requirements

Install

curl -fsSL https://agentpc.pawanpaudel.com.np/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,
5. checks everything with agentpc doctor.

Upgrade later with agentpc update. Installer options:

Images

Every VM is a copy-on-write clone of a read-only image, so it starts from a clean install and costs only a few MB. A bare ubuntu means ubuntu-24.04, and a bare windows means windows-11-25h2. Pin the full name when the release matters, for example in test harnesses.

Images are clean installs, like a customer's new PC: Windows has no Visual C++ redistributable, no .NET beyond the built-in Framework 4.8.1, and no PowerShell 7. If a program fails with a missing VCRUNTIME140.dll, its installer is missing a dependency. Each image records what it is:

$ agentpc image info windows
{
  "os": "windows",
  "version": "Windows 11 Pro 25H2 (build 26200.6584)",
  "arch": "arm64",
  "built": "20260927",
  "desktop_server": "cua-driver 0.30.1",
  …
}

How it works

• Hypervisor. VMs run in QEMU on Apple's Hypervisor.framework, natively on Apple Silicon.
• 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 state instead of booting: ~1 s / ~4 s instead of ~14 s / ~25 s.
• Checkpoints. A checkpoint pauses the VM for a few seconds, writes its memory to a file and clones its disk with an APFS copy-on-write clone.
• 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).
• 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.
• Agent-ready guests. Each snapshot capture turns off what interrupts unattended work (SmartScreen, updates, first-run pop-ups, Ubuntu's background apt jobs) and installs Chrome on Ubuntu.

Networking

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

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

Configuration

Each VM gets its own ports on 127.0.0.1, derived from its slot number n:

Windows guest tips

GUI installers return immediately

Run them silently and wait for the process, then check its exit code:

Start-Process installer.exe -ArgumentList '/S' -Wait -PassThru

Windows Update is disabled

So updates never interrupt a task. This also blocks DISM /online and Add-WindowsCapability. Re-enable it temporarily:

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

Defender is on

Only SmartScreen is off. Defender may quarantine a fresh or unsigned test binary, so exclude your work directory:

Add-MpPreference -ExclusionPath C:\work

Hardware limits

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

Troubleshooting

Security

• Everything listens on 127.0.0.1 only.
• The desktop-control servers inside VMs are unauthenticated; any process on your Mac can reach them.
• Each VM has its own VNC password. The viewer URL from agentpc info carries it, so the browser viewer connects without a prompt.
• Guests use the fixed login agent / agent. Windows VMs have UAC prompts, SmartScreen and Windows Update turned off.
• VMs can reach the internet and your Mac through 10.0.2.2. Use --offline for untrusted software.
• Treat VMs as throwaway sandboxes, not a place for secrets.

Uninstall

$ agentpc uninstall            # asks first; -y skips the prompt

This stops all VMs, removes the MCP server from every agent, and deletes ~/.agentpc (--keep-data keeps it) and the binary. It leaves shared things alone and lists them: the PATH line, QEMU, and the Claude plugin.