agentpc MCP server
Commit Nov 10, 2026Provides AI agents with instant, resettable Windows, Ubuntu, and Arch Linux desktop VMs on Apple Silicon via MCP.
Also known as pawanpaudel93/agentpc
- Stars
- 4
- Tools
- 16
- Downloads, 30 days
- —
- Latest version
- 0.1.12
- Last commit
- Nov 10, 2026
- License
- MIT
What is agentpc MCP?
agentpc provides AI agents with instant, resettable Windows, Ubuntu, and Arch Linux desktop VMs on Apple Silicon via MCP. It exposes 16 tools, such as list_vms, create_vm, reset_vm.
Summary generated from the project's README
About agentpc MCP server
agentpc provides AI agents with instant, resettable desktop environments running on Apple Silicon Macs. It allows agents to interact with Windows 11, Ubuntu, and Arch Linux ARM through a single Rust binary that utilizes QEMU and Apple's hypervisor. This setup enables agents to perform complex tasks like clicking, typing, and running commands within a real operating system. The server works locally on 127.0.0.1, ensuring privacy and security for all computations.
Developers can connect this server to various MCP clients including Claude Desktop, Claude Code, Cursor, VS Code, and Gemini CLI. The system supports advanced features like checkpoints to save memory and disk states, allowing agents to return to specific points before risky operations. It also provides tools for taking PNG screenshots, managing files via upload and download, and forwarding ports to access internal VM services from the host Mac. Users can monitor agent activity through a built-in browser viewer.
What you can do with it
- 1Test installation scriptsAn agent can create a fresh Ubuntu VM to verify that a setup script runs correctly on a clean machine.
- 2Automate desktop interactionsAn AI can be instructed to open a specific application and perform manual UI tasks like typing notes.
- 3Execute terminal commandsAgents can run bash or PowerShell commands and retrieve the output directly through the MCP interface.
- 4Recover from errorsA developer can instruct an agent to save a checkpoint before a dangerous step and restore it if something fails.
Written from the project's README. Every use case is checked against a quote from it.
agentpc MCP tools 16
Detected from the READMElist_vmscreate_vmreset_vmdelete_checkpointdelete_vmtake_screenshotrun_commandget_job_statuslist_jobswait_for_servicestop_jobforward_port
Show all 16 toolsShow fewer tools
read_vm_loglist_desktop_toolsuse_desktop_toolinspect_desktop
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubagentpc
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).
resetreturns 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-installsets 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 --openor MCPopen_in_browser: trueto 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-x86appsrun 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.1only.
Requirements
| Requirement | Details |
|---|---|
| Hardware | Apple Silicon Mac (M1 or later; tested on M4) |
| OS | A macOS version QEMU supports: the current one and, for up to two years, the previous one (tested on macOS 15) |
| Runtime | QEMU from Homebrew (the installer handles it, installing Homebrew too if needed) |
| Memory | 4 GB per running Ubuntu or Arch VM, 8 GB per running Windows VM |
| Disk | ~10 GB per Ubuntu or Arch image, ~30 GB per Windows image (each including its snapshot) |
Installation
curl -fsSL https://agentpc.pawanpaudel.com.np/install.sh | sh
The installer:
- downloads the latest release and verifies its checksum,
- installs
agentpcto~/.local/bin(nosudo) and adds it to yourPATH, - installs QEMU with Homebrew if it's missing (installing Homebrew first if needed, which asks for your password once),
- registers the MCP server with the agents it finds (
agentpc mcp-install), - 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:
| Variable | Effect |
|---|---|
AGENTPC_VERSION=0.1.0 |
Install a specific version |
AGENTPC_INSTALL_DIR=<dir> |
Install somewhere other than ~/.local/bin |
AGENTPC_NO_MCP=1 |
Skip registering the MCP server |
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 <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). 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
| Tool | Description |
|---|---|
list_vms |
VMs (owner, state, size, checkpoints, viewer and, for running x86apps VMs, x86_tso) and the available images with their OS versions |
create_vm |
Create a VM (optionally of a given version, size, or offline) and wait until its desktop is ready. Retrying it with the same name and image in the same session returns the VM already created, booting it if it was stopped. open_in_browser: true opens its viewer in the Mac’s default browser after readiness (default false; per-call only). Browser-launch failure warns without failing creation. from_checkpoint: "<vm>/<label>" makes a new, independent VM from a checkpoint's disk instead: it boots cold, os/version may be omitted (if given, they must be the source's image), and the checkpoint's memory, port forwards, owner, offline and job records are not carried over. Errors before any work: invalid_checkpoint_ref, no_such_vm, no_such_checkpoint, image_mismatch |
start_vm / stop_vm |
Boot a stopped VM / shut one down cleanly |
reset_vm |
Discard all changes: back to a fresh copy of the image |
checkpoint_vm / restore_vm |
Save a VM's disk and memory under a label; go back to it in seconds. A running VM's guest first writes its pending data to disk (at most ~10 s; otherwise the reply says "not flushed") |
delete_checkpoint |
Delete one checkpoint by label; the VM is untouched |
delete_vm |
Delete a VM with its disk and checkpoints |
take_screenshot |
PNG screenshot from the hypervisor; save_to also writes it to a path on your Mac |
run_command |
Run a command (PowerShell on Windows, bash on Ubuntu and Arch); returns typed structuredContent plus the readable exit code, stdout and stderr (each stream trimmed to its first and last 10,000 characters). At a foreground run's timeout (default 120 s) agentpc attempts to stop it and keeps its partial output, and the reply says whether the stop was confirmed. A foreground run whose request is cancelled or whose client disconnects is stopped the same way (request_cancelled); background: true returns a detached job id for get_job_status that cancellation does not stop |
get_job_status |
Check a job by its id: queued, running, exited (with its code), stopped, ended without an exit code, or missing, plus its log. wait_seconds (0 to 30, default 0) waits without ever stopping the job; cursor reads the log incrementally. Also takes the job_id of a foreground run whose outcome was uncertain |
list_jobs |
Find jobs again when their id was lost (a cancelled or disconnected run_command, a lost reply): the VM's job records, newest id first, as metadata only (id, kind, state, exit code, stop reason, which records exist, file times), never a command, environment, output or log. limit 1 to 100 (default 20); next_cursor continues below the last job shown. Read-only |
wait_for_service |
Wait until a TCP port accepts a connection, or an HTTP path answers its expected status (default 200, redirects not followed), on the VM's own 127.0.0.1; timeout_seconds 1 to 120 (default 30). Optionally ends early when a run_command job_id is proven to have failed. Read-only: it never stops or restarts the service or the job |
stop_job |
Stop a background job (or a foreground run's job_id) and everything it started (on Linux its systemd scope, which processes that detach stay in, when the guest has a user manager, else the processes marked with the job and their descendants; on Windows its process tree). For a job that already exited, it stops only what the job left running |
upload_file / download_file |
Copy files or folders between your Mac and a VM |
forward_port |
Reach a server running in a VM from your Mac (TCP over an SSH tunnel, works even for servers bound to the guest's own 127.0.0.1; or protocol: "udp" for a UDP server listening on 0.0.0.0) |
list_forwards / delete_forward |
List a VM's active port forwards / stop one by its host port (and optional protocol) |
read_vm_log |
Read the tail of a VM's qemu or serial log, for when a VM won't boot or the desktop is unreachable |
list_desktop_tools |
List the desktop-control tools inside a VM, with each one's required arguments and whether it's read-only (or one tool's full schema, with its annotations); a wrong name returns close matches |
use_desktop_tool |
Call one of them: click, type, launch apps, read the UI tree, … A call with wrong arguments or a wrong name returns the tool's arguments or close matches. Marked destructive |
inspect_desktop |
The read-only twin of use_desktop_tool, with the same arguments: it runs a tool only if the VM's driver explicitly marks it read-only, and refuses anything else before dispatching it |
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.
Command results and job output
run_command and get_job_status return structuredContent that matches the outputSchema they
declare (schema_version 1), next to the readable text scripts have always parsed. The text is the
legacy exit code: N / STATE: ... form in a single block, not a JSON copy, so clients that join text
blocks see no extra output. Read the typed fields and isError; the full contract is in
AGENTS.md.
run_command:stateisexited,timed_out,not_started,connection_lost,startedorcancelled. It carriesrequest_cancelled,exit_code,stdout,stderrwith byte counts and truncation flags,termination_confirmed,effect_unknown,recovery_action, anexecution_id(null only when the call failed before one was issued, such as an unknown VM) and, when you need a handle, ajob_id. Every nonzero exit, timeout, failed start or lost connection is a tool error, even a timed-out command whose own exit code is known to be 0.- Timeouts: at
timeout, agentpc attempts to stop the command and what it started and keeps the partial stdout and stderr.termination_confirmed: truemeans it verified that none of the processes it identified is left: on Linux the command's transient systemd user scope when the guest's user manager is available, the processes marked with its execution id and their descendants (all that is checked without a user manager), and its verified root; on Windows its verified process tree, best effort. It is not a sandbox guarantee. System services, other systemd units and Windows services, scheduled tasks and WMI-created processes are not covered. A command whose exit code the VM recorded but whose run had not ended by the timeout (a child it left may have held its output, or it ended right at the deadline) returns that exit code withtimed_out: true, after cleanup verified that none of the processes it identified remains. If it can't confirm the stop (termination_confirmed: false), or the connection was lost before the command's end was known (connection_lostwitheffect_unknown: true),effect_unknownis true and thejob_idworks withget_job_statusandstop_job; aconnection_lostwitheffect_unknown: falsecarries the recordedexit_codeand nojob_id; commands are never retried automatically, and onlyrecovery_action: retrymeans one provably never ran. The reply follows a timeout within a few seconds usually, and about 50 seconds at most. - Cancellation: a foreground
run_commandis stopped in the VM, as at a timeout, when its request is cancelled (notifications/cancelled), the client disconnects or the MCP session ends. The result hasrequest_cancelled: trueand is a tool error:cancelledwithtermination_confirmed: truewhen the stop was verified,exitedwith the command's code when it had already finished,not_startedwhen it never began (no retry is suggested), orcancelledwithtermination_confirmed: false,effect_unknown: trueandrecovery_action: stop_jobwhen the stop could not be verified. A client that cancelled usually never receives that reply: find the run again withlist_jobs, thenget_job_statusreportsstoppedwithstop_reason: request_cancelled(ornot_started). A request cancelled before anything was sent starts nothing. A background start is detached on purpose: cancelling its request, disconnecting or ending the session does not stop the job; usestop_job.AGENTPC_KEEP_RUNNING=1keeps the VMs, not the foreground commands, and a hard kill of the MCP server cleans up nothing (the job records stay in the VM). - Foreground exit codes are the low 8 bits SSH reports (Windows
exit -1reads 255). A Linux foreground command is limited to 92 KiB (94,208 UTF-8 bytes) of text, checked before anything is sent (a bigger one isnot_started, with no retry); for a bigger script,upload_fileit and run the file. get_job_status: withoutwait_secondsorcursorit answers at once with the lasttail_lineslines (at most 16 KiB) and anext_cursor. Withwait_secondsit waits for the job to leaverunning(with acursor, for new output) and returns the current state withwait_timed_out: trueif nothing happened; a wait never stops the job. Acursor(anext_cursor, or"start") returns at most 16 KiB from that byte position and advances by exactly what it returned, so output is neither repeated nor skipped; UTF-8 characters are never split. A cursor that no longer matches the log (VM reset or restored, guest reboot, log replaced, shortened or rewritten) is reset and said so (cursor_reset,cursor_reset_reason); that detection is best effort.missingmeans nothing has recorded itself under the id yet, which doesn't prove it never started. An unreachable VM is an error, never reported asended.list_jobs: read-only, metadata only (job_id,kind,state,exit_code,stop_reason,log_available,records,recorded_at,finished_at, anoteon an unresolved entry), newest id first,limit1 to 100 (default 20). Whenhas_moreis true, passnext_cursorascursor; pages continue below the last job shown within the VM as the first page saw it, so jobs created meanwhile do not shift them. A cursor from before a VM reset, restore or recreation iscursor_stale: the VM's generation changed and its records may differ from what the earlier pages listed (a restored checkpoint can keep some), so the listing cannot safely continue; call again without a cursor. The listing is best effort, not an immutable history: records age out, and a huge job directory keeps only its first entries (scan_truncated), so jobs may be missing. Aqueued,missingorunknownentry is unresolved, not proof the command never started. Cancelling the call abandons only the listing.wait_for_service: polls only the VM's own IPv4127.0.0.1(never another host, a URL or a proxy).protocol: "tcp"(default) is ready when a connection is accepted;"http"is ready when oneGET path(/by default, a path not a URL; no credentials in it, because it is echoed in the result and visible in the VM's process list) returnsexpected_status(default 200).pathandexpected_statusare HTTP-only and refused withtcp. Redirects are not followed, and no response body, header or guest text is returned: the result hasstate(ready,timed_out,job_failed,cancelled,error), the lasttcp/http_outcome(status_matched,redirect,status_mismatched,no_response,malformed) /http_status,attempts,waited_msanderror_code(such asprobe_unsupportedwhen the guest's bash has no/dev/tcpor it has notimeoutcommand). Anything butreadyis a tool error, andtimed_outkeeps the last observation.timeout_secondsbounds the waiting, not the wall clock: a call can run about 5 s past it. Withjob_idthe wait ends early (job_failed) only for a proven failure: a nonzero exit, a stopped job or one that never started; a job that exited 0 (a server may outlive its wrapper), is queued, running, missing or unreadable is not failure. Ready describes the endpoint, not a process: nothing checks who owns the port, so it does not prove the job started it. Waiting never stops the service or the job, and cancelling it only stops probing, but each probe makes short-lived connections (and one GET), so it can consume a one-shot listener.inspect_desktopchecks the driver's ownreadOnlyHintbefore each dispatch and refuses an unmarked, unknown or not read-only tool before dispatching it, with nothing run (looking up the annotations does ask the VM's driver). The marking is the driver's claim, a guard against mistakes rather than a guarantee. Compact observation:get_window_statewithinclude_screenshot: falsereturns the element tree without a screenshot, and itsqueryargument narrows what comes back.
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. inspect_desktop is marked read-only and only
runs tools the driver marks read-only, so clients can auto-approve looking while still confirming
acting. To approve agentpc's tools up front:
| Client | Setting |
|---|---|
| Claude Code | Allow mcp__agentpc (all of its tools) with /permissions, or in permissions.allow in settings |
| Codex | default_tools_approval_mode = "approve" under [mcp_servers.agentpc] in ~/.codex/config.toml |
| Gemini CLI | "trust": true on the agentpc server in ~/.gemini/settings.json |
| Others | The client's own tool-approval settings |
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.
| Guest | Desktop | Desktop-control server |
|---|---|---|
| Windows | Windows 11 (ARM64), 1280x800, Edge | cua-driver (over SSH) |
| Ubuntu | Ubuntu 24.04 or another release, XFCE on X11, 1280x800, Google Chrome; double-clicking a .deb installs it |
cua-driver (over SSH) |
| Arch | Arch Linux ARM (rolling), XFCE on X11, 1280x800, Chromium; sudo pacman -Syu --noconfirm <pkg> |
cua-driver (over SSH) |
AGENTS.md has usage tips for agents.
CLI reference
agentpc MCP questions
What tools does agentpc MCP provide?
It exposes 16 tools, including list_vms, create_vm, reset_vm, delete_checkpoint, delete_vm.
What operating systems can I run?
You can run Windows 11 (ARM), Ubuntu (XFCE), and Arch Linux ARM (XFCE) desktops.
How fast can I create a new VM?
VMs are ready in approximately 1 second for Ubuntu or Arch, and about 4 seconds for Windows.
Can I see what the AI agent is doing in the VM?
Yes, every VM has a browser viewer that allows you to watch the agent's actions.
Does this work on Intel Macs?
No, the hardware requirement is an Apple Silicon Mac (M1 or later).