agentpc

agentpc

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

Website: https://agentpc.pawanpaudel.com.np

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

Features

• Instant VMs. New VMs resume from a saved snapshot of a running desktop: ready in ~1 s (Ubuntu, Arch) 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), Ubuntu 24.04 or another release (XFCE), and Arch Linux ARM (XFCE), each with a desktop-control server agents can drive: cua-driver on all of them.
• 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, Chromium on Arch) 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. Use agentpc create ubuntu --open or MCP open_in_browser: true to open it in the Mac’s default browser after readiness; neither opens a tab by default.
• x86 apps. x64 Windows apps run through Prism; ubuntu-x86apps / arch-x86apps run x86_64 Linux programs and amd64 containers through FEX.
• 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://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 (agentpc mcp-install),
5. checks everything with agentpc doctor.

To upgrade later, run agentpc update (or agentpc update --check to just look); rerunning the installer works too. 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

Arch Linux ARM:

agentpc create arch          # first run: downloads 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 .

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). Updating an existing JSON mcpServers.agentpc or Codex [mcp_servers.agentpc] entry preserves custom environment/options while refreshing the managed command and arguments, and keeps the comments and blank lines around them. Config is written through a private temporary file. Invalid config is refused, not replaced; multiline TOML values are edited as complete values. 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

If a desktop-tool reply starts with a reconnect note (the VM or its driver restarted), earlier snapshot ids and browser sessions are gone: take a new snapshot and run browser_prepare again.

VMs an MCP session created, started, reset or restored are stopped (never deleted) when the session ends, unless AGENTPC_KEEP_RUNNING=1. If the session's server was killed instead, the next MCP server to start stops them; list_vms marks such VMs owner_running: false, and create_vm with the same name and image hands one back to the session that asks. Session shutdown is bounded at about 45 s per VM (lock wait, ACPI shutdown, then a forced quit); a VM another session has taken over is left alone.

Approval prompts

Every desktop action goes through use_desktop_tool, which is marked destructive, so clients that confirm tool calls ask before each click or keystroke. To approve agentpc's tools up front:

That approves every agentpc tool, including upload_file and download_file, which read and write files on your Mac. The VMs themselves are throwaway: reset_vm undoes anything done inside one.

| Arch | Arch Linux ARM (rolling), XFCE on X11, 1280x800, Chromium; sudo pacman -Syu --noconfirm | cua-driver (over