agentpc

agentpc

在 Mac 上为 AI Agent 提供可即时启动、可重置的 Windows、Ubuntu 和 Arch Linux ARM 桌面。

网站：https://agentpc.pawanpaudel.com.np

agentpc 为 AI Agent（Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、VS Code 或 任何 MCP 客户端）提供可供使用的真实桌面计算机：几秒内创建虚拟机，让 Agent 点击、 输入、截屏和运行命令，然后将其重置为干净状态。它是一个独立的 Rust 二进制程序，使用 QEMU 在 Apple 的虚拟机监控程序上运行虚拟机，并通过 MCP 为 Agent 提供服务。

目录

• 功能
• 要求
• 安装
• 快速开始
• 与 AI Agent 配合使用
• CLI 参考
• 镜像
• 配置
• 工作原理
• 故障排除与客户机提示
• 卸载
• 安全性
• 开发
• 许可证

功能

• 即时启动虚拟机。 新虚拟机从正在运行的桌面保存快照恢复：Ubuntu 和 Arch 约需 1 秒，Windows 约需 4 秒即可就绪。reset 同样能快速将虚拟机恢复到干净状态。
• 检查点。 在执行有风险的步骤前保存正在运行的虚拟机（磁盘和内存），并在几秒内返回到 确切的保存状态。
• 真实桌面。 支持 Windows 11（ARM）、Ubuntu 24.04 或其他版本（XFCE），以及 Arch Linux ARM（XFCE）；所有系统都配备 Agent 可驱动的桌面控制服务： cua-driver。
• 一个 MCP 服务搞定一切。 Agent 可自行创建、操作、截屏和删除虚拟机。 兼容任何 MCP 客户端；agentpc mcp-install 可配置常用客户端。
• Shell 和屏幕访问。 通过 SSH 运行 PowerShell 或 bash；直接从虚拟机监控程序获取 PNG 截图， 约需 40 毫秒，即使客户机正在启动或卡住也可以。
• 文件和端口。 在 Mac 与虚拟机之间复制文件和文件夹，也可从 Mac 访问 虚拟机内运行的服务。
• 为 Agent 准备就绪的客户机。 提供 1280x800 桌面和浏览器（Windows 上为 Edge，Ubuntu 上为 Chrome，Arch 上为 Chromium）， 并关闭会打断无人值守工作的弹窗、更新重启和后台任务。
• 实时查看。 每台虚拟机都有浏览器查看器，可查看 Agent 正在执行的操作。使用 agentpc create ubuntu --open 或 MCP 参数 open_in_browser: true，可在就绪后通过 Mac 的 默认浏览器打开；默认情况下，两者都不会打开标签页。
• x86 应用。 x64 Windows 应用通过 Prism 运行；ubuntu-x86apps / arch-x86apps 可运行 x86_64 Linux 程序和 amd64 容器，使用的是 FEX。
• 多版本并行运行。 可同时运行 Ubuntu 22.04、24.04 和 26.04，或多个 Windows 11 版本。每个镜像都会记录其操作系统版本、来源和构建日期。
• 本地且私密。 所有操作都在 Mac 上进行，且仅监听 127.0.0.1。

要求

要求	详情
硬件	Apple Silicon Mac（M1 或更新型号；已在 M4 上测试）
操作系统	QEMU 支持的 macOS 版本：当前版本以及之前两年内发布的版本（已在 macOS 15 上测试）
运行时	通过 Homebrew 安装的 QEMU（安装程序会处理；如有需要，也会安装 Homebrew）
内存	每台正在运行的 Ubuntu 或 Arch 虚拟机需 4 GB；每台正在运行的 Windows 虚拟机需 8 GB
磁盘	每个 Ubuntu 或 Arch 镜像约 10 GB；每个 Windows 镜像约 30 GB（均包含快照）

安装

curl -fsSL https://agentpc.pawanpaudel.com.np/install.sh | sh

安装程序会：

1. 下载最新版本并验证其校验和，
2. 将 agentpc 安装到 ~/.local/bin（无需 sudo），并将其添加到你的 PATH，
3. 如果尚未安装，则通过 Homebrew 安装 QEMU（如有需要，会先安装 Homebrew；此过程会要求你输入一次密码），
4. 为检测到的 Agent 注册 MCP 服务（agentpc mcp-install），
5. 运行 agentpc doctor 检查所有内容。

之后要升级，请运行 agentpc update（或者运行 agentpc update --check 仅检查）；重新运行安装程序也可以。安装程序选项：

变量	作用
AGENTPC_VERSION=0.1.0	安装指定版本
AGENTPC_INSTALL_DIR=<dir>	安装到 ~/.local/bin 以外的位置
AGENTPC_NO_MCP=1	跳过注册 MCP 服务

如需从源码构建，请参阅开发。

快速开始

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 的许可不允许重新分发 Windows 镜像，因此每台 Mac 都要自行构建一次。除非你已有镜像，否则 agentpc 会从 Microsoft 下载官方 Windows 11 ARM64 ISO（7.3 GB，已验证校验和）：

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

然后向你的 Agent 提出类似这样的要求：

• “创建一个 Ubuntu VM，打开终端并运行 uname -a。”
• “重置 ubuntu-1，并检查我的安装脚本能否在干净的机器上正常工作。”
• “在 windows-1 上打开记事本，输入一段简短的文字，并给我看一张截图。”

如需自行查看 VM，请打开 agentpc info <name> 输出的查看器 URL。

与 AI Agent 配合使用

agentpc 是一个 MCP 服务（agentpc mcp，stdio）。一个服务可处理所有 VM。

Claude 插件

在 Claude Code 中安装 agentpc 插件。它集成了 MCP 服务和一项技能，能教会 Claude 何时以及如何使用这些 VM：

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

插件会运行已安装的 agentpc 二进制文件，因此请先安装该文件（参见安装）。安装插件时，它已经为 Claude Code 注册了 MCP 服务，因此 agentpc mcp-install 会跳过 Claude Code，以避免重复注册。

其他 Agent

为每个已安装的受支持 Agent 注册服务（安装程序会自动执行此操作）：

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

支持的 Agent：Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI 和 VS Code（注册后请重启 Claude Desktop）。更新现有的 JSON mcpServers.agentpc 或 Codex [mcp_servers.agentpc] 条目时，会保留自定义环境变量和选项，同时刷新由程序管理的命令和参数，并保留其周围的注释和空行。配置会通过私有临时文件写入。遇到无效配置时会拒绝操作，而不会替换配置；多行 TOML 值会作为完整值进行编辑。对于其他 MCP 客户端，请添加：

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

此代码库还包含项目级配置（.mcp.json、.codex/config.toml、.cursor/mcp.json、.gemini/settings.json、.vscode/mcp.json），因此在克隆目录中打开的 Agent 会自动发现该服务。

工具

工具	描述
list_vms	列出虚拟机（所有者、状态、大小、检查点、查看器，以及运行中的 x86apps 虚拟机的 x86_tso）和可用映像及其操作系统版本
create_vm	创建虚拟机（可选指定版本、大小或离线模式），并等待其桌面就绪。在同一会话中使用相同的 name 和映像重试时，会返回已创建的虚拟机；如果虚拟机已停止，则会启动它。open_in_browser: true 会在虚拟机就绪后于 Mac 的默认浏览器中打开查看器（默认为 false；仅对此次调用生效）。如果启动浏览器失败，会发出警告，但不会导致创建失败
start_vm / stop_vm	启动已停止的虚拟机 / 正常关闭虚拟机
reset_vm	丢弃所有更改：还原为映像的新副本
checkpoint_vm / restore_vm	将虚拟机的磁盘和内存保存到指定标签下；几秒内即可恢复
delete_checkpoint	按标签删除一个检查点；不影响虚拟机
delete_vm	删除虚拟机及其磁盘和检查点
take_screenshot	从虚拟机监控程序获取 PNG 截图；save_to 还会将其写入 Mac 上的指定路径
run_command	运行命令（Windows 上使用 PowerShell，Ubuntu 和 Arch 上使用 bash）；返回退出代码、标准输出和标准错误。前台运行在达到 timeout（默认为 120 s）时会被终止，并返回部分输出；background: true 会返回供 get_job_status 使用的作业 ID
get_job_status	按作业 ID 检查后台作业：运行中、已退出（含退出代码）、已停止或结束时没有退出代码，并返回日志末尾内容
stop_job	停止后台作业及其启动的所有进程（Linux 上为其 systemd 作用域，脱离作用域的进程除外；Windows 上为其进程树）。如果作业已退出，则只会停止该作业遗留的运行中进程
upload_file / download_file	在 Mac 和虚拟机之间复制文件或文件夹
forward_port	从 Mac 访问虚拟机中运行的服务（通过 SSH 隧道转发 TCP，即使服务绑定到来宾系统自己的 127.0.0.1 也可用；或使用 protocol: "udp" 访问监听在 0.0.0.0 上的 UDP 服务）
list_forwards / delete_forward	列出虚拟机的活动端口转发 / 按主机端口（及可选协议）停止一项转发
read_vm_log	读取虚拟机 qemu 或 serial 日志的末尾内容，用于排查虚拟机无法启动或桌面无法访问的问题
list_desktop_tools	列出虚拟机中的桌面控制工具，并注明各工具所需的参数及是否为只读；名称错误时会返回相近的名称
use_desktop_tool	调用其中一个工具：单击、输入文字、启动应用、读取 UI 树等。参数错误或名称错误时，会返回该工具的参数或相近的名称

如果桌面工具的回复以重新连接提示开头（虚拟机或其驱动程序已重启），则先前的快照 ID 和浏览器会话已失效：请重新获取快照，并再次运行 browser_prepare。

MCP 会话创建、启动、重置或恢复的虚拟机将在会话结束时停止（不会删除），除非设置了 AGENTPC_KEEP_RUNNING=1。如果会话的服务被终止，则下一个启动的 MCP 服务会停止这些虚拟机；list_vms 会将此类虚拟机标记为 owner_running: false，而 create_vm 使用相同名称和映像时，会将虚拟机交还给发起请求的会话。每台虚拟机的会话关闭时间上限约为 45 s（等待锁、ACPI 关机，然后强制退出）；已被另一个会话接管的虚拟机不会受到影响。

审批提示

每项桌面操作都会通过 use_desktop_tool 执行，该工具被标记为具有破坏性，因此会确认工具调用的客户端会在每次点击或按键前询问。若要预先批准 agentpc 的工具：

客户端	设置
Claude Code	使用 /permissions，或在设置中的 permissions.allow 里允许 mcp__agentpc（其所有工具）
Codex	在 ~/.codex/config.toml 的 [mcp_servers.agentpc] 下设置 default_tools_approval_mode = "approve"
Gemini CLI	在 ~/.gemini/settings.json 中为 agentpc 服务设置 "trust": true
其他	客户端自己的工具审批设置

这会批准 agentpc 的所有工具，包括 upload_file 和 download_file，它们会在你的 Mac 上读取和写入文件。虚拟机本身都是一次性的：reset_vm 会撤销在其中执行的所有操作。

客户机	桌面环境	桌面控制服务
Windows	Windows 11 (ARM64)，1280x800，Edge	cua-driver（通过 SSH）
Ubuntu	Ubuntu 24.04 或其他版本，X11 上的 XFCE，1280x800，Google Chrome；双击 .deb 即可安装	cua-driver（通过 SSH）
Arch	Arch Linux ARM（滚动更新），X11 上的 XFCE，1280x800，Chromium；sudo pacman -Syu --noconfirm <pkg>	cua-driver（通过 SSH）

AGENTS.md 中有供 Agent 参考的使用技巧。

CLI 参考

虚拟机

对虚拟机执行操作的命令可以接受多个名称（agentpc stop a b），会在执行任何操作前检查所有名称，并在出现失败后继续处理（只要有一项失败，退出状态就是 1）。每条命令都有 --help。

命令	说明
agentpc create <image> [name] [--memory GB] [--cpus N] [--offline] [--open]	从 ubuntu、windows、arch 或某个版本（例如 ubuntu-22.04）创建虚拟机；如果 Ubuntu 和 Arch 镜像不存在，则会获取这些镜像。名称最多可包含 64 个字母、数字、. - _。--memory 范围为 2–64 GB，--cpus 范围为 1–16（默认值为 4）；使用非默认配置时会冷启动，而不是恢复运行。--offline：无法访问互联网或这台 Mac。--open（别名 --open-in-browser）：在 Mac 的默认浏览器中打开已就绪虚拟机的查看器；默认关闭
agentpc list [--json] (ls)	列出虚拟机和镜像；--json 会返回与 MCP list_vms 工具相同的数据
agentpc info <name>	查看器 URL（含 VNC 密码）、SSH 和 VNC 详情、检查点；对于 x86apps 虚拟机，还会显示 x86 程序的运行方式（x86 programs: FEX, hardware|emulated TSO）
agentpc start <name>… | --all	启动已停止的虚拟机
agentpc stop <name>… | --all	正常关闭虚拟机；磁盘会保留。对于在 agentpc 将电源按钮交给 logind 之前捕获的 Arch 镜像，每次关闭时都会等待约 3 分钟超时，直到运行 agentpc image snapshot <image> 刷新镜像
agentpc reset <name>…	丢弃所有更改：恢复为镜像的全新副本
agentpc rm <name>… (delete)	删除虚拟机及其磁盘和检查点
agentpc checkpoint <name> <label> [-d]	保存虚拟机的磁盘和内存（运行中的虚拟机会暂停约 5 秒），或删除检查点
agentpc restore <name> <label>	将虚拟机精确恢复到某个检查点的状态（几秒内恢复运行）
agentpc ssh <name> [command]	运行命令，或在未指定命令时打开 Shell
agentpc screenshot <name> [file]	保存 PNG 截图
agentpc cp <src> <dst>	复制文件；虚拟机一侧的格式为 <name>:<path>，例如 agentpc cp app.msi windows-1:Downloads/
agentpc forward <name> <guest-port> [host-port]	将 127.0.0.1:<host-port> 转发到运行中虚拟机的端口（通过 SSH）。--udp 改为转发 UDP（目标为监听在 0.0.0.0 上的客户机服务）。--list 显示某个虚拟机的端口转发；--rm <host-port> 停止一项转发（添加 --udp/--tcp 可指定协议）

镜像命令

命令	描述
agentpc image pull <image>	下载已发布的镜像，例如 ubuntu、ubuntu-22.04、ubuntu-x86apps、arch、arch-x86apps，或固定版本的 ubuntu-24.04-YYYYMMDD / arch-rolling-YYYYMMDD。如果失败后再次拉取，会从中断处继续，并复用已验证的部分
agentpc image build <image> [--iso <path>]	在本地构建镜像（Ubuntu 约 3 分钟，Arch 约 6 分钟，ubuntu-x86apps 约 8 分钟，arch-x86apps 约 10 分钟，Windows 约 12 分钟 + ISO 下载时间）
agentpc image ls (list)	列出本地镜像及其操作系统版本
agentpc image info <image>	查看镜像的版本、来源、构建日期和桌面服务
agentpc image rm <image>… (delete)	删除本地镜像（如果有虚拟机、构建、拉取或快照正在使用该镜像，则会拒绝删除）
agentpc image snapshot <image>	将此 agentpc 的访客系统设置应用到镜像，并重新捕获虚拟机恢复时使用的快照（构建和拉取时会执行此操作）；必须先删除使用该镜像的虚拟机
agentpc image push <image>	维护者：将 Ubuntu 或 Arch 镜像发布到 ghcr.io

设置

命令	描述
agentpc mcp	通过标准输入输出运行 MCP 服务（Agent 启动该服务）
agentpc mcp-install [clients…]	将 MCP 服务注册到 Agent（如果已安装插件，则跳过 Claude Code；并提高 Codex 的 MCP 超时时间，以免缓慢的构建和启动触发超时）
agentpc mcp-uninstall [clients…]	从 Agent 中移除 MCP 服务
agentpc update [--check]	更新到最新版本（已验证校验和；保留镜像和虚拟机；运行 agentpc list 会标记访客系统设置较旧的镜像，运行 agentpc image snapshot <image> 可刷新镜像）。别名：upgrade。如果二进制文件所在目录不可写入，会提示运行 sudo agentpc update 或通过 AGENTPC_INSTALL_DIR 重新安装
agentpc doctor	检查先决条件，并显示 macOS 和 QEMU 版本（macOS 低于 15 时会发出警告，因为 x86apps 虚拟机将模拟 TSO；QEMU 低于 9.0 时也会发出警告）
agentpc clean [-n]	释放磁盘空间：清理需要时可重新下载的内容（ISO、云镜像、约 830 MB 的 Arch Linux ARM 压缩包）、中断的构建、拉取或检查点留下的残余文件，以及其他版本的 TSO 库。绝不触碰镜像或虚拟机，并保留正在运行的构建、拉取或推送所需的内容（标记为“kept …”）；列出没有虚拟机使用的镜像
agentpc uninstall [--keep-data] [-y]	移除 agentpc（参见卸载）
agentpc completions <shell>	输出 bash、zsh 或 fish 的 Tab 补全内容，例如 agentpc completions zsh > ~/.zfunc/_agentpc

镜像

镜像是只读磁盘，其中已安装操作系统、桌面和 Agent 工具。每个虚拟机都是镜像的写时复制克隆，因此虚拟机始终从干净安装开始，且只占用几 MB 空间。

镜像命名为 <os>-<version>，可以并行安装多个镜像；每个虚拟机都会记住其源镜像。单独使用 ubuntu 表示 ubuntu-24.04，单独使用 arch 表示 arch-rolling，单独使用 windows（或 windows-11）表示 windows-11-25h2。为了节省 12 分钟的构建时间，如果尚未构建 25H2，create 和 image info 会回退使用你最新安装的 Windows 11 镜像。如果版本对测试至关重要，请指定完整名称，例如在测试框架中。

镜像	来源	获取方式
ubuntu = ubuntu-24.04	官方 Ubuntu 24.04 云镜像	image pull（首次执行 create 时自动获取），或 image build
ubuntu-<release>	cloud-images.ubuntu.com/releases 中的任意版本，例如 22.04、26.04	image build ubuntu-22.04；如果已发布，也可以使用 image pull
ubuntu-x86apps = ubuntu-24.04-x86apps	Ubuntu 24.04，还可运行 x86_64 和 i386 Linux 程序（参见 x86_64 Linux 程序）	image pull（首次执行 create 时自动获取；如果下载失败，则在本地构建，约需 8 分钟），或 image build ubuntu-x86apps
ubuntu-22.04-x86apps	22.04，可运行 x86 程序（x86apps 仅适用于 22.04 和 24.04）	image build ubuntu-22.04-x86apps；如果已发布，也可以使用 image pull
arch = arch-rolling	Arch Linux ARM（Arch 的社区移植版），从其 aarch64 tarball 在 Ubuntu 辅助虚拟机中安装	image pull（首次执行 create 时自动获取；如果下载失败，则在本地构建，约需 6 分钟），或 image build arch（需要 Ubuntu 镜像；如果缺失则会获取）
arch-x86apps = arch-rolling-x86apps	Arch Linux ARM，还可运行 x86_64 和 i386 Linux 程序（参见 x86_64 Linux 程序）	image pull（首次执行 create 时自动获取；如果下载失败，则在本地构建，约需 10 分钟），或 image build arch-x86apps
windows-11-25h2（windows）	Windows 11 25H2（Home/Pro），Microsoft 提供的 7.3 GB ISO	image build windows
windows-11-24h2、windows-11-23h2	较早的 Windows 11 版本（Home/Pro）	image build windows-11-23h2
windows-<name>	你自己的 Windows 11 ARM64 Home/Pro ISO	image build windows-<name> --iso <path>

只有 ARM64 Windows 能在 Apple Silicon 上以原生速度运行，因此不提供仅支持 x64 的版本； 而 Windows 10 的 ARM64 版本在 Apple Silicon 上启动时会卡住，因此最低版本为 Windows 11。 无人值守安装使用 Home/Pro 安装密钥，因此不支持 Enterprise 和 LTSC ISO。如果 ~/Downloads 中的 ISO 文件名表明其对应正在构建的版本，则会使用该 ISO； 使用 --iso 时，ISO 也必须与版本名称匹配（24H2 ISO 不能用于构建 windows-11-25h2）。 Windows 未激活运行（仅显示水印，不影响其他功能）；如有需要，请使用你自己的密钥激活。

镜像均为全新安装，就像客户刚买的新电脑：Windows 不包含 Visual C++ 可再发行组件， 不包含 .NET（仅内置 .NET Framework 4.8.1），也不包含 PowerShell 7。某个程序在你的 机器上能运行，却因缺少 VCRUNTIME140.dll 或类似文件而无法在虚拟机中运行，这说明它缺少本应由安装程序提供的依赖项。不提供 Microsoft 的评估版 ISO：它们安装后已过期，并且每小时都会关机。

Microsoft 只提供当前的 ARM64 ISO；较早版本需从存档镜像站（archive.org、bobpony.com）下载。每个 ISO 都会根据固定的 SHA-256 校验，因此镜像站无法替换为修改过的文件，并会保存在 ~/.agentpc/cache 中。所有 ISO 均为 en-us；如需其他语言，请自行下载并通过 --iso 指定。

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

每个镜像都会记录自身信息（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": "cua-driver 0.30.3",
  "iso_sha256": "32cde007…"
}

已发布的镜像存放在同一个软件包 ghcr.io/pawanpaudel93/agentpc 中，并以镜像名称作为标签。Windows 镜像无法再分发：

标签	含义	拉取命令
ubuntu-24.04	Ubuntu 24.04 的最新构建（也标记为 ubuntu）	agentpc image pull ubuntu
ubuntu-<release>	其他版本的最新构建	agentpc image pull ubuntu-22.04
ubuntu-24.04-YYYYMMDD	某个特定构建（固定版本；无法在本地构建）	agentpc image pull ubuntu-24.04-YYYYMMDD
ubuntu-24.04-x86apps	带有 x86 程序的 Ubuntu 24.04 最新构建	agentpc image pull ubuntu-x86apps
ubuntu-24.04-x86apps-YYYYMMDD	某个特定构建（固定版本；无法在本地构建）	agentpc image pull ubuntu-24.04-x86apps-YYYYMMDD
arch-rolling	Arch Linux ARM 的最新构建（也标记为 arch）	agentpc image pull arch
arch-rolling-YYYYMMDD	某个特定构建（固定版本；无法在本地构建）	agentpc image pull arch-rolling-YYYYMMDD
arch-rolling-x86apps	带有 x86 程序的 Arch Linux ARM 最新构建	agentpc image pull arch-x86apps
arch-rolling-x86apps-YYYYMMDD	某个特定构建（固定版本；无法在本地构建）	agentpc image pull arch-rolling-x86apps-YYYYMMDD

固定版本的构建只能下载：image build 会拒绝构建；如果下载失败，create 也不会改为构建当天的版本。短名称同样可用（ubuntu-x86apps-YYYYMMDD 对应 ubuntu-24.04-x86apps-YYYYMMDD）。推送会更新滚动标签，但不会更改已有的日期标签，即使重新捕获本地映像也一样。日期标签仍指向其原始发布版本，不一定是当前滚动映像。不同机器上的发布者必须串行推送新的日期标签：由于注册表端没有不可变标签，标签检查和创建并非原子操作。

配置

变量	默认值	描述
AGENTPC_HOME	~/.agentpc	存放映像、VM、密钥和缓存的位置
AGENTPC_IMAGE_REPO	ghcr.io/pawanpaudel93/agentpc	image pull/push 使用的软件包（按映像名称标记）
WIN_ISO	之前下载的文件、~/Downloads 中匹配的 ISO，否则下载	不带 --iso 时，image build windows-… 使用的 Windows ISO

每个 VM 都会在 127.0.0.1 上使用独立端口，端口号根据其槽位编号 n 计算（现有 VM 会在下次启动时切换到新端口）：

端口	用途
47000 + n	SSH
47200 + n	noVNC WebSocket（供查看器使用）
47300 + n	VNC
8100	浏览器查看器，由所有 VM 共用

桌面和 sudo 的来宾登录凭据为 agent / agent；SSH 只接受 agentpc 的密钥登录（已禁用密码登录）。每个 VM 还有自己的 VNC 密码（参见安全性）。

工作原理

• **虚拟机管理程序。**虚拟机通过 Apple 的 Hypervisor.framework（HVF）在 QEMU 中运行，原生运行于 Apple Silicon 上，中间没有其他层。
• **即时启动。**构建或下载镜像后，agentpc 会启动一次，等待桌面和控制服务器运行，然后保存虚拟机的内存。新虚拟机从保存的状态恢复，而不是重新启动（约 1 秒／4 秒，而不是约 15 秒／25 秒）。stop 后执行 start 会正常启动；reset 则会再次恢复一个全新的副本。
• **检查点。**创建检查点时，虚拟机会暂停几秒，内存会写入文件，磁盘会被克隆（采用 APFS 写时复制克隆，因此只有虚拟机写入更多数据时才会占用空间）。恢复检查点的方式与新虚拟机相同。运行中的虚拟机每个检查点占用的磁盘空间约等于正在使用的内存（Windows 约为 3–4 GB）；agentpc checkpoint <name> <label> --delete 可删除一个检查点，删除虚拟机则会删除其所有检查点。
• **快照保留在本地。**内存快照取决于 Mac 的芯片和 QEMU 版本，因此只发布磁盘；每次拉取后都会重新捕获快照（约需一分钟）。每个快照都会记录 QEMU 机器类型，因此 QEMU 升级后仍可恢复。
• 稳健性。create 会预先检查可用磁盘空间和 RAM，checkpoint 会检查磁盘空间；恢复操作具有原子性（失败时虚拟机保持原样），并会恢复之前处于暂停状态的虚拟机；同一虚拟机上的操作会串行执行，崩溃遗留的过期 pid 文件会被检测出来，而不会被盲目信任。客户机时钟会遵循 Mac 的时区。SSH keepalive 会保持长时间调用不中断，桌面工具调用会在 120 秒后放弃，无法启动的查看器也不会再导致虚拟机启动失败。浏览器查看器（noVNC）会通过固定的校验和下载。
• **镜像分发。**Ubuntu 和 Arch 镜像是 GitHub Container Registry 上的 OCI 制品：一个压缩后的 qcow2 被拆分为 64 MB 的分片，并行下载且进行校验和验证。拉取前会检查可用磁盘空间；如果下载中断，会保留已验证的分片，再次拉取时会从这些分片继续。每个层和镜像配置都会根据其清单摘要和大小进行校验，合并后的磁盘必须通过 qemu-img check，才能替换当前镜像。
• **固定版本的下载内容。**镜像构建所下载的内容均固定版本并经过验证：FEX 按标签和提交固定，Ubuntu 和 Arch x86 根文件系统以及 cua-driver 的安装程序和二进制文件按 SHA-256 校验，Arch Linux ARM tarball 按其签名验证，Chrome 则从 Google 的签名 apt 仓库获取。构建和快照会检查客户机运行的是固定版本的 cua-driver。
• **Windows 构建。**agentpc 会在 ISO 旁写入一个小型设置磁盘：其中包含无人值守安装应答文件（改编自 dockur/windows-arm）、Red Hat 的 ARM64 virtio 驱动，以及一个用于首次登录时安装 OpenSSH 和 cua-driver 的脚本（关闭遥测）。随后，Windows Setup 会在 QEMU 中运行，无需点击；如果该脚本失败，构建会立即停止（请在客户机中查看 C:\OEM\failed.txt 和 C:\OEM\setup.log），而不是超时。
• **Ubuntu 构建。**通过 cloud-init 配置官方云镜像：安装 XFCE（运行于 X11）、启用自动登录并安装 cua-driver（固定版本，以确保工具名称与本文档一致；关闭遥测）。随后会禁用 cloud-init，避免克隆后重新配置。若要启用 cua-driver 遥测，请在虚拟机中运行 cua-driver telemetry enable。
• **Arch 构建。**克隆 Ubuntu 镜像并添加一个空白的第二磁盘，然后运行脚本将 Arch Linux ARM tarball 安装到该磁盘上：配置 systemd-boot、启用 XFCE（运行于 X11）和自动登录，并安装 Chromium 及相同固定版本的 cua-driver。该磁盘将成为镜像。经过验证的 tarball 会保留在 ~/.agentpc/cache/alarm，供下次构建使用（运行 agentpc clean 会将其删除）。
• **x86apps 构建。**在 ubuntu-x86apps 和 arch-x86apps 上，guests/<os>/x86apps.sh 会从源代码构建 FEX（标签和提交在该脚本中固定）并将其编译为 static-pie，同时应用 guests/ubuntu/fex.patch（以便 x86 容器能够运行），并安装 x86 根文件系统：Ubuntu 的根文件系统采用 squashfs，内核会在启动时以只读方式挂载（而不是通过 FUSE 使用 FEX，因为沙盒化服务无法这样做）；Arch Linux 的根文件系统则会解包，以便 fex-pacman 能向其中添加软件包。 这些虚拟机使用的 QEMU 会加载 src/hvf_tso.c，从而启用 CPU 的 TSO 模式；agentpc 会在每次启动后检查结果并告知 FEX。若 TSO 关闭，FEX 会改为模拟 x86 内存排序。
• **适用于 Agent 的客户机。**每次捕获快照时，准备脚本都会关闭会打断无人值守工作的功能（Windows SmartScreen、更新、首次运行和提示弹窗；Ubuntu 的后台 apt 任务；Arch 的 pacman 定时器），并在 Ubuntu 上安装 Google Chrome，以供 cua-driver 的浏览器工具使用（Arch 镜像预装 Chromium）。

故障排除与虚拟机使用提示

• 检查设置： agentpc doctor。
• 查看屏幕： agentpc screenshot <name>，或打开 agentpc info <name> 提供的查看器 URL。
• 日志位于每台 VM 的 ~/.agentpc/instances/<name>/ 中：qemu.log（QEMU 错误）和 serial.log（虚拟机控制台）。
• VM 状态异常： agentpc reset <name>。
• image build/pull/rm 拒绝执行： 仍有 VM 依赖该镜像；请先对这些 VM 执行 agentpc rm。 如果有正在运行的构建任务使用该镜像，构建和 rm 也会拒绝执行（Arch 构建会在 Ubuntu 镜像的克隆中运行）；如果有正在运行的拉取或快照任务，rm 也会拒绝执行。请等任务完成后重试。带固定版本的 …-YYYYMMDD 镜像只能拉取。
• 镜像构建或快照提示虚拟机运行的是另一个 cua-driver： 该镜像由不同版本的 agentpc 构建；请使用 agentpc image build <image> 重新构建。
• agentpc update 无法写入其目录（例如归 root 所有的 /usr/local/bin）：运行 sudo agentpc update，或使用 AGENTPC_INSTALL_DIR=<dir> 在该目录重新安装。

网络

每台 VM 都位于 QEMU 用户模式 NAT 后，因此 VM 之间相互隔离，但共用 Mac 的网络（在 Mac 上配置的 VPN 或代理会应用于 VM 的出站流量）。

• 从 Mac 访问 VM 中的服务： agentpc forward <name> <guest-port> [host-port] （MCP：forward_port），然后连接到 127.0.0.1:<host-port>。该连接通过 SSH 隧道传输，因此可以访问绑定到虚拟机自身 127.0.0.1 的服务，且不受 Windows 防火墙影响。 转发会持续到 VM 停止或你将其移除为止（--rm <host-port> / delete_forward）； --list（MCP：list_forwards）会显示某台 VM 的转发。
• UDP 服务（游戏、DNS、QUIC、中继）：添加 --udp（MCP：protocol: "udp"）。UDP 转发使用 QEMU 主机转发，而不是 SSH 隧道，因此它会访问虚拟机的网络地址（10.0.2.15）：服务必须监听 0.0.0.0，而不是 127.0.0.1；在 Windows 上还需要防火墙规则。与 TCP 转发一样，VM 停止、还原或重置时 UDP 转发会被丢弃；离线 VM 不支持 UDP 转发。
• 从虚拟机内访问 Mac： 10.0.2.2 是 Mac 主机地址；NAT 会将其映射到 Mac 的环回地址，因此，在虚拟机内可通过 10.0.2.2:<port> 访问监听在 127.0.0.1 或 0.0.0.0 的开发服务器。
• VM 之间互通： 没有直接路由。将服务器 VM 的端口转发到 Mac （forward_port(B, guest_port, host_port)），然后从另一台 VM 连接到 10.0.2.2:<host_port>。对于 UDP，传入 protocol: "udp"，并让 B 的服务器监听 0.0.0.0。
• 离线 VM（--offline / offline: true）无法访问 10.0.2.2 或互联网，但从 Mac 转发的 TCP 端口仍可访问这些 VM。UDP 转发在此类 VM 上不起作用：离线网络会丢弃虚拟机发送的所有 UDP 数据报，包括回复。
• 企业代理 / CA： 虚拟机不会继承 Mac 的代理设置。请在虚拟机内设置 HTTP_PROXY 和 HTTPS_PROXY，并使用 Import-Certificate（Windows）、update-ca-certificates（Ubuntu）或 sudo trust anchor --store <cert>（Arch）导入企业根 CA。

虚拟机重启

重启虚拟机（例如安装 Windows Update 或运行某些安装程序）会断开 SSH 连接。对同一台 VM 调用 start_vm——即使 VM 已在运行，它也会等待桌面重新就绪——或者等 VM 恢复后重试一次 run_command。

Windows 虚拟机使用提示

• GUI 安装程序会立即返回。 请以静默模式运行并等待进程结束： Start-Process installer.exe -ArgumentList '/S' -Wait -PassThru（开关因程序而异： /S、/silent、/quiet），然后检查其 ExitCode。run_command 进程会在 命令返回时结束，因此请使用 background: true 启动服务和 GUI 应用。

• 映像中已禁用 Windows Update（wuauserv 服务已停止并设为 Disabled，且已设置 NoAutoUpdate 策略），因此更新不会打断任务。这也会阻止从 Windows Update 获取文件的可选功能——DISM /online（例如 .NET 3.5）和 Add-WindowsCapability（RSAT、语言包；OpenSSH 已安装）。如需使用这些功能， 请暂时重新启用 Windows Update，之后再将其设回原状态：

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

• Defender 实时保护已开启。 agentpc 只会禁用 SmartScreen，不会禁用 Defender，因此 Defender 可能会隔离刚构建的或未签名的测试二进制文件。请使用 Add-MpPreference -ExclusionPath C:\work 将工作目录添加到排除项，或使用 Set-MpPreference -DisableRealtimeMonitoring $true 关闭实时监控（篡改防护可能会阻止后一种操作）。

• x64 应用通过仿真运行。 虚拟机运行的是 Windows 11 ARM64。x64 和 x86 程序 （安装程序、桌面应用、命令行工具）通过 Windows 内置的 Prism 仿真运行，速度约为原生程序的 2–4 倍； x64 驱动、内核模式软件和反作弊程序无法运行。下载页面提供 ARM64 版本时，请优先选择。

Arch 虚拟机使用提示

• 软件包： sudo pacman -Syu --noconfirm <pkg>（Arch 不支持部分升级）。 第一次运行 -Syu 可能会升级整个系统，因此请为 run_command 设置较长的 timeout，或使用 background: true；内核升级后，请先重启（start_vm），再加载新模块。
• /tmp 是 tmpfs，每次启动时都会清空（与 Ubuntu 不同）；请将文件保存在其他位置。

x86_64 Linux 程序

Ubuntu 和 Arch 客户机是 arm64。对于 x86_64（以及 i386）Linux 程序，请从 ubuntu-x86apps 或 arch-x86apps 镜像创建 VM（agentpc create ubuntu-x86apps，或使用 version: "x86apps" 调用 create_vm）。该镜像会安装 FEX，在每个 x86 程序运行时将其转换为 arm64；内核和桌面环境仍以原生方式运行。直接运行程序（./tool）。

• 速度。 大多数代码的运行速度约比原生慢 2 倍，Node 等 JIT 运行时则慢约 6–7 倍。在 macOS 15 或更高版本上，agentpc 还会将这些 VM 的 CPU 切换为 TSO（x86 的 内存排序方式），让 FEX 无需模拟它：多线程代码的运行速度最高可提升约 40%，原生 arm64 代码也不会变慢。agentpc list --json（list_vms）会通过 x86_tso 显示 VM 使用的是 hardware 还是 emulated。FEX 会将转换后的代码保存在 ~/.cache/fex-emu 中，因此程序第二次启动的速度会比第一次快几倍。
• 库。 x86 程序会从镜像附带的 x86 文件树（x86 Ubuntu 或 x86 Arch Linux）中找到常用库（libc、libstdc++、GTK 等）。在 Ubuntu 上，使用 amd64 软件包安装其他库：sudo apt install libfoo:amd64（镜像已配置好 amd64 软件包源），或者使用 sudo apt install ./app_amd64.deb 安装 amd64 .deb；其安装脚本（由原生 dpkg 运行）在 uname -m、arch 和 dpkg --print-architecture 中看到的都是 x86_64 机器，因此可以通过会检查这些信息的供应商软件包检测。在安装 amd64 库时，可能会升级对应的 arm64 库，因为两者必须是同一版本。Arch 不支持多架构，因此在 arch-x86apps 上，x86 程序使用 FEX 的 x86 Arch Linux 文件树；运行 sudo fex-pacman -Sy --noconfirm --needed <pkg> 可向其中安装更多 x86 软件包（x86 pacman 在 chroot 中运行，并固定使用该文件树对应的 Arch Linux Archive 日期，以避免部分升级）。
• Go 程序在 FEX 下会崩溃，除非设置 GODEBUG=asyncpreemptoff=1；镜像已为 x86 程序设置此项。
• x86 Electron 和 Chromium 应用（VS Code、Slack、Chrome 等）启动时会因 zygote_host 错误而中止：FEX 无法创建 Chromium 沙箱使用的命名空间。使用 --no-sandbox 启动它们（例如 code --no-sandbox）。
• x86 容器可以运行：安装 Docker 或 Podman（在 Arch 上：sudo pacman -Syu --noconfirm docker && sudo systemctl start docker），然后运行 docker run --platform linux/amd64 <image>。 FEX 会使用镜像自带的 x86 文件运行这些容器。
• x86 服务可在 systemd 下运行，即使是没有主目录的系统用户也可以（此时 FEX 会将配置和代码缓存保存在单元的 StateDirectory= 中，或保存在私有目录 /tmp/fex-emu-<uid> 中）。带有 MemoryDenyWriteExecute= 或 LockPersonality= 的单元会阻止 FEX 运行，就像它们会阻止任何 JIT 一样。因此，systemd 生成器（/etc/systemd/system-generators/agentpc-fex）会为 ExecStart 是 x86 程序的所有单元放宽这两项设置；原生服务仍保留这两项设置，systemctl cat 会显示相应的 drop-in 配置。若单元通过其他方式（例如脚本）运行 x86 程序，则需要运行 sudo fex-unit <unit>（使用 --undo 可移除设置）；否则服务启动时会在 FEX 内部因 SIGSEGV 而退出，并生成 AArch64 核心转储，看起来像是应用崩溃。使用 ProtectSystem=strict 时，请为单元提供可写目录（StateDirectory= 或 PrivateTmp=）。
• 仅支持 x86 的安装程序若会检查 uname -m，可在 x86 bash 下原样运行： sudo FEXBash ./install.sh。其中的 uname、useradd、systemctl 等工具随后都会作为 x86 程序运行，因此脚本会识别出一台 x86_64 机器。对于粘贴的命令块 （curl ... | sudo VAR=... bash -s -- args），请先启动 FEXBash，再将命令块粘贴到其中：真正的 sudo 是 setuid 程序，会以原生方式运行，因此 FEXBash 会将自己的 sudo 放在 PATH 的首位，让它调用真正的 sudo 通过 FEXBash 启动命令，并保持其为 x86 程序。
• 不包括： x86 内核模块和驱动。这是指令转换，并非一台 x86 机器。

硬件限制

虚拟机显示分辨率固定为 1280x800，配备仅支持 2D 的 virtio GPU（没有 3D/GPU 加速；WebGL 由软件渲染或不可用），且没有音频设备。

卸载

agentpc uninstall            # asks first; -y skips the prompt

这会停止所有虚拟机，从 mcp-install 注册过该 MCP 服务的所有 Agent 中移除它，删除 ~/.agentpc（镜像、虚拟机、检查点和密钥；使用 --keep-data 可保留这些数据），并删除 agentpc 二进制文件。它不会改动共享项目，并会列出这些项目：安装程序添加的 PATH 条目（其他工具也会使用 ~/.local/bin）、QEMU（如果没有其他用途，可运行 brew uninstall qemu 卸载）以及 Claude 插件（/plugin uninstall agentpc@agentpc）。

若只想释放磁盘空间，agentpc clean 会删除可重新下载的内容，agentpc image rm <image> 会删除不再使用的镜像。

安全性

• 所有服务仅监听 127.0.0.1。
• 虚拟机内的桌面控制服务未经身份验证；Mac 上的任何进程都可以访问它们。
• 每台虚拟机都有自己的 VNC 密码（位于其实例目录中的 vnc-pass，权限模式为 0600）。agentpc info <name> 输出的查看器 URL 包含该密码（&password=…），因此浏览器查看器无需提示即可连接；原生 VNC 客户端（vnc://127.0.0.1:<port>）会要求输入密码——可从该 URL 复制，或读取 ~/.agentpc/instances/<name>/vnc-pass。
• 虚拟机桌面和 sudo 使用固定登录凭据 agent / agent。SSH 只接受 agentpc 的密钥，因为每台虚拟机的 SSH 端口都可从其他虚拟机和本地用户访问。
• ~/.agentpc 仅供你访问（0700）：其中存有虚拟机磁盘、RAM 检查点和 SSH 密钥。
• 浏览器查看器链接会在 # 后附带 VNC 密码，不会在任何请求中发送；并且只有当 8100 端口上的服务确认为 agentpc 自身时，才会提供该链接。命令会使用新生成的 HMAC-SHA256 挑战来验证查看器；私有身份密钥绝不会通过 HTTP 提供，而且已观察到的响应无法验证不同的挑战。
• 为避免阻碍 Agent，Windows 虚拟机已关闭 UAC 提示、SmartScreen 和 Windows Update。请勿将它们用于需要这些保护的用途。
• 虚拟机可以访问互联网，也可以通过网关 10.0.2.2 访问 Mac 上的服务。创建虚拟机时使用 --offline（在 create_vm 中设为 offline: true）即可切断这两种访问，例如用于运行不可信软件；SSH、查看器和转发端口仍可使用。
• MCP 工具带有注释：list_vms、take_screenshot、list_desktop_tools、get_job_status、list_forwards 和 read_vm_log 为只读工具；会丢弃或覆盖状态的工具（包括会向 Mac 写入文件的 download_file）标记为破坏性操作，以便客户端据此自动批准或要求确认。
• 请将虚拟机视为一次性沙盒，而非存放机密的地方。

开发

cargo build --release                  # target/release/agentpc
scripts/check.sh                       # all CI checks, including site SEO/link checks
scripts/smoke.py --bin target/release/agentpc   # drives fresh VMs through the MCP server
python3 scripts/lifecycle-stress.py --bin target/release/agentpc --rounds 3

生命周期压力测试套件需要已有且最新的 Ubuntu 快照；它不会下载或构建镜像。它会短暂持有空闲镜像锁以延迟克隆，检查排队的启动/删除调用会等待初始化，并验证单工作线程的 MCP 服务仍能正常响应。随后，它会对具名创建、启动、停止和删除操作进行并发竞争，并检查被杀死的会话的孤儿恢复以及会话的正常关闭。它只使用由任务独占且名称唯一的 VM，之后会删除这些 VM；如果存在可能被回收的无关运行中孤儿 VM，则拒绝启动。日志不会包含原始 MCP 响应和查看器凭据。CI 会检查语法；VM 测试在 Apple Silicon 上本地运行。

更改访客脚本、桌面驱动程序或 MCP 网关后，运行冒烟测试（先重新构建受影响的镜像）。该测试会检查访客是否能在不出现首次运行对话框的情况下打开应用、桌面工具是否能读取和输入，以及网关是否会说明错误参数。

guests/ 中的访客配置文件会嵌入二进制文件。AGENTS.md 为贡献者和编码 Agent 描述了代码布局。

发布（维护者）

1. 在更新至最新且干净的 main 上，运行 scripts/release.sh X.Y.Z（需要已登录的 gh、用于 npx 的 Node，以及 jq）。该脚本会在各处设置版本（若 Cargo.toml 已是 X.Y.Z，则跳过），运行 CI 检查，构建 dist/（二进制压缩包、MCP bundle agentpc-X.Y.Z.mcpb、对应的 .sha256 文件、填好的 server.json 和 NOTES.md，以及按 Conventional Commit 提交标题分组的自上一个标签以来的发布说明），然后在提交 chore: release vX.Y.Z、标记 vX.Y.Z、推送 main 和该标签并创建 GitHub Release 前询问确认。--dry-run 会在构建 dist/ 后停止。
2. 发布 Linux 镜像（ubuntu、ubuntu-x86apps、arch 和 arch-x86apps）：使用可写入软件包的令牌登录 oras（gh auth refresh -s write:packages，然后运行 gh auth token | oras login ghcr.io -u <user> --password-stdin），接着对每个镜像运行 agentpc image build <image> 和 agentpc image push <image>。推送会上传 64 MB 的分块、重试失败操作，并将软件包关联到此仓库；在软件包设置中将其设为公开即可。
3. 发布到 MCP Registry：运行 brew install mcp-publisher、mcp-publisher login github，然后运行 mcp-publisher publish dist/server.json。

许可证

MIT © 2026 Pawan Paudel