terminal-mac README

项目的 README,来自 github.com/govijr/terminal-mac。合并为一个 markdown 文件:README.md。

terminal-mac

Buy Me A Coffee

A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.

terminal-mac is an early release candidate for Apple silicon. Apple Virtualization runs a real macOS guest. A bundled helper inside that guest captures its screen and posts input events. A terminal viewer streams that screen using Kitty or iTerm2 graphics. Agent commands use the same helper without moving the physical Mac's pointer or changing its clipboard.

The guest is a separate Mac: it has its own apps, files, accounts and permissions. It does not inherit your running host apps or signed-in sessions. The VM still consumes host CPU, memory and storage.

Requirements

Install and run

curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash

The installer downloads the latest release and verifies its SHA-256 before installing. You can also extract a release ZIP and run bash install.sh from it.

The installer places one launcher in ~/.local/bin and the bundled runtime under ~/.local/lib/terminal-mac. Add ~/.local/bin to your PATH to use simply terminal-mac. It needs no administrator rights and does not edit your shell configuration. bash install.sh --prefix /absolute/path selects another location.

Running terminal-mac in an interactive terminal starts the guided flow. terminal-mac up does the same explicitly. It automatically downloads/caches a compatible Apple restore image, installs a virtual Mac, boots it and checks the guest helper. Later runs reuse the existing VM and reconnect. Unsupported terminals get the native desktop window.

Current status: early release candidate. Releases are self-signed (no Apple notarization), which the curl installer doesn't need. Live guest acceptance on a clean Mac is still pending.

Use with agents

terminal-mac gives agents computer use in a separate virtual Mac, through MCP tools (screenshot, click, drag, scroll, type, key, status) and a skill that teaches the observe → act → verify loop.

Claude Code, with the MCP server and skill in one plugin:

/plugin install terminal-mac --marketplace govijr/terminal-mac

Or add them separately:

claude mcp add terminal-mac -- terminal-mac mcp
terminal-mac skills install                 # → ~/.claude/skills/terminal-mac/SKILL.md

Other MCP clients (Cursor, VS Code, Codex, Windsurf…): paste the output of terminal-mac mcp --config into the client's MCP settings. Use terminal-mac mcp NAME for a VM other than default.

Any agent with a skills folder: terminal-mac skills install --dir PATH, or npx skills add govijr/terminal-mac --skill terminal-mac. In an AGENTS.md, a line like "Before using the virtual Mac, run terminal-mac skills get" gives the agent instructions that match the installed version.

The tools only drive the guest helper. They never touch your own desktop. When the guest is at its login screen, they say so, so the agent can ask you to sign in.

One-time guest setup

The first run opens the virtual Mac's window. Complete macOS setup and create its user account. Inside the guest, open Finder → /Volumes/My Shared Files/tools → TerminalMacGuest.app once. The helper installs itself in the guest's ~/Applications, launches that installed copy and registers for future guest logins, subject to macOS approval.

Use its two buttons to grant Screen Recording and Accessibility inside the guest. Reopen it if macOS asks. If needed, its Guest Login Items button opens the startup setting. The host needs neither privacy permission. Once both guest permissions are ready, the CLI automatically continues to the terminal desktop. From then on the helper lives as a computer icon in the guest's menu bar: it opens at login without showing a window, the icon's menu shows the permission state, and Open Setup Window… brings the window back.

This is guided setup, not an unattended guest installation. Apple documents automatic account provisioning for macOS 27 guests; this build targets the APIs available in the installed macOS 26 SDK and does not implement that newer flow. See Apple's provisioning documentation.

terminal-mac up work                  # another virtual Mac
terminal-mac up --ipsw /path/mac.ipsw  # use a local image
terminal-mac up --no-view             # wait for agent readiness, then return JSON
terminal-mac up --detach              # install/boot, return without waiting for guest setup
terminal-mac up --plan                # show steps without network access or disk changes

The first download may take time; packaging cannot eliminate downloading and installing macOS. The image cache is reused, and URLSession resume data is retained after recoverable network failures. A hard process kill may require the current download to restart. An incomplete installation with recorded hardware can be retried by up using a compatible restore image; an already installed VM is never reinstalled by up.

Build from source

bash scripts/build.sh
./dist/terminal-mac doctor

The build creates dist/TerminalMac.app, including TerminalMacGuest.app, and the dist/terminal-mac launcher. Virtualization needs the host executable's com.apple.security.virtualization entitlement; use the packaged launcher instead of the unsigned Swift build product.

It is signed with the self-signed "Govijr Code Signing" identity when your keychain has it (bash scripts/create-signing-identity.sh makes one), and ad-hoc otherwise. A stable identity keeps the guest helper's permissions across rebuilds; ad-hoc builds need them granted again. RELEASING.md covers signing and publishing.

Create your first Mac

# Show the URL and version without downloading anything:
./dist/terminal-mac image

# Explicitly download Apple's latest supported restore image (several GB):
./dist/terminal-mac image --output /tmp/RestoreImage.ipsw

# Install macOS. The disk is sparse, and the IPSW is not copied into the VM bundle.
./dist/terminal-mac create default --ipsw /tmp/RestoreImage.ipsw
./dist/terminal-mac start default --window

Complete macOS Setup Assistant in the VM window and create a guest account. Inside the guest:

  1. Open Finder → /Volumes/My Shared Files/tools.
  2. Open TerminalMacGuest.app. It installs itself to the guest's ~/Applications and opens the installed copy.
  3. Use the helper's buttons to grant Screen Recording and Accessibility in the guest's System Settings. Reopen the helper if macOS asks. The host does not need either permission.

If both toggles are on but terminal-mac action NAME status still reports false, for example after a helper signed with a different identity replaced the one that was approved, run terminal-mac action NAME permissions. It clears the stale grants inside the guest and prompts again. 4. Keep the guest logged in and the helper running. It registers itself for guest login; approve that setting if macOS requests it.

On the host:

./dist/terminal-mac action default status
./dist/terminal-mac hide default
./dist/terminal-mac view default

The viewer supports typing, left/right clicks, double and triple clicks, dragging, scrolling, arrows and common control keys. Ctrl+G opens a palette of Mac shortcuts (Spotlight, Mission Control, copy/paste, close/quit and more), because terminals keep ⌘ for themselves. Ctrl+] exits the viewer while the VM keeps running. Closing the native VM window hides it and also leaves the VM running.

The guest helper keeps a ScreenCaptureKit stream open while a viewer is watching. It sends a frame only when the screen changes (up to 30 fps), already sized to the pixels the terminal draws, as lossless lz4-compressed pixels. Kitty and Ghostty receive those frames through shared memory rather than the pty. An idle desktop costs nothing, and the stream stops 15 seconds after the viewer leaves. From build 4 on, the guest helper updates itself: within 30 seconds of a newer build appearing in the shared tools folder, it installs that build and relaunches. Helpers from build 3 and earlier still work but poll full screenshots, and the header shows "snapshots". Update those once by opening /Volumes/My Shared Files/tools/TerminalMacGuest.app in the guest. Releases are signed with one unchanging self-signed certificate, so the guest keeps its Screen Recording and Accessibility approvals across updates.

Guest helper updates must satisfy the running helper's designated code requirement. Stable certificate-signed builds retain their update identity. An ad-hoc rebuild generally has a different code identity and is refused by automatic updates; install it manually inside the guest and grant its permissions again.

Agents can drive the guest through an MCP server: claude mcp add terminal-mac -- "$PWD/dist/terminal-mac" mcp default. See docs/AGENT.md.

New VMs use a 2x HiDPI display (for example 2560×1600 pixels at 220 ppi for the default 1280×800 points), so text stays sharp on Retina terminals. Switch a stopped VM with terminal-mac display default --hidpi or --standard.

The automounted volume is supplied by macOS virtio-fs. If it is absent, check the guest's macOS version and the VM log; this prototype has no fallback guest transport.

Give an agent computer control

./dist/terminal-mac action default screenshot --output /tmp/guest.png
./dist/terminal-mac action default click 640 400
./dist/terminal-mac action default type 'Hello from the agent'
./dist/terminal-mac action default key cmd+space
./dist/terminal-mac action default key return
./dist/terminal-mac action default scroll --dy -300 --x 640 --y 400

Commands return JSON and a nonzero exit status on failure. Screenshots return a local host PNG path. Coordinates start at the top-left and match the screenshot's dimensions; screenshots use guest display points to keep input coordinates consistent on Retina displays. snapshot is currently a screenshot alias, not an accessibility-tree snapshot.

The agent instructions are in docs/AGENT.md. No global agent settings are modified.

Lifecycle and resources

./dist/terminal-mac ls
./dist/terminal-mac status default
./dist/terminal-mac pause default
./dist/terminal-mac resume default
./dist/terminal-mac show default
./dist/terminal-mac stop default          # request a normal guest shutdown
./dist/terminal-mac stop default --force  # immediate power-off; unsaved guest work can be lost

Customize a new VM with --cpus 4 --memory 4 --disk 64 --width 1280 --height 800 (width and height are in points; add --standard for a 1x display). CPU, memory and disk arguments are logical CPUs, GiB and GiB respectively. --offline omits the guest network device; the shared-folder control channel still works, though some macOS setup workflows may require networking.

Networking

By default the guest uses macOS NAT: the host hands out addresses on 192.168.64.0/24 and relays DNS at the gateway. VPN and proxy apps that run in TUN mode (Clash, Surge, sing-box and similar) can leave that relay silent, so the guest keeps an IP but cannot resolve names and looks offline. --network user instead bundles gvproxy (Apache-2.0, the user-space network stack behind podman machine and vfkit) and runs DHCP, DNS and NAT in user space, with names resolved by the host's own resolver, so the guest stays online wherever the host is:

scripts/fetch-gvproxy.sh                              # once: download gvproxy into vendor/ (checksum pinned)
scripts/build.sh                                      # bundles it into TerminalMac.app
./dist/terminal-mac create default --ipsw … --network user
./dist/terminal-mac network default --user            # or switch an existing, stopped VM (--nat, --offline)

In user mode the guest is 192.168.127.2 with gateway and DNS at 192.168.127.1; the host answers at 192.168.127.254 (host.containers.internal). gvproxy runs as a child of the VM's background process, logs to runtime.log and exits with it. terminal-mac doctor reports whether gvproxy is bundled; status reports the mode in use.

VM data lives in ~/Library/Application Support/terminal-mac/machines/NAME/. TERMINAL_MAC_HOME overrides the data root. Each VM has an exclusive file lock, a sparse disk, hardware identity, auxiliary boot storage, machine.json, a private host-control mailbox, the guest exchange directory, and runtime.log. A VM boot runs as a separate background process. Lifecycle commands must use the same TERMINAL_MAC_HOME as the process that started it.

An interrupted or failed installation leaves its directory and installed: false for diagnosis. It is never silently overwritten. To retry, ensure no installer/VM is running, move that incomplete directory aside, then create the VM again. There is deliberately no destructive VM-delete command yet.

Isolation model

VM cloning, rollback checkpoints, accessibility snapshots, fully unattended guest setup, terminal splits and tmux transport remain future work. The native Virtualization framework does not itself render a Mac into a terminal or offer an agent input API; this project supplies the guest transport and terminal presentation layers.

Development and validation

CLANG_MODULE_CACHE_PATH=/tmp/terminal-mac-modules \
SWIFTPM_MODULECACHE_OVERRIDE=/tmp/terminal-mac-modules \
swift test --disable-sandbox --scratch-path /tmp/terminal-mac-build \
  --cache-path /tmp/terminal-mac-cache \
  --config-path /tmp/terminal-mac-config --security-path /tmp/terminal-mac-security

Tests cover mailbox round trips, expiry and cleanup, file-boundary defenses, name/option validation, fragmented UTF-8 and terminal input sequences. These are automated protocol checks, not evidence that a guest was installed, booted, granted permissions, or controlled successfully. See docs/VALIDATION.md for recorded results and the live checklist.

References: terminal-browser, Apple's macOS virtualization sample, VZVirtualMachineView, ScreenCaptureKit.

Sponsor

terminal-mac is free and maintained in my own time. Sponsoring keeps it that way.

terminal-mac (govijr/terminal-mac)

正在搜索数据库…

这是什么?这是一个独立的 macOS 桌面,由计算机操作类智能体控制,你可以在终端中查看并操控它。
它是真正的 Mac,还是只是模拟器?它是运行在你自己的 Apple silicon Mac 上的真正 macOS 虚拟机,基于 Apple Virtualization 运行,拥有自己的应用、文件和账户。
怎样让它运行起来?运行安装程序,它会下载最新版本、校验 SHA-256,并在 ~/.local/bin 中放置一个启动器。然后在交互式终端中运行 terminal-mac,启动引导流程,下载 macOS 并启动虚拟机。你需要在虚拟机窗口中完成 macOS 设置,并亲自为客机辅助程序授予“屏幕录制”和“辅助功能”权限。
开始之前我需要准备什么?一台运行 macOS 14 或更高版本的 Apple silicon Mac,首次下载 macOS 时需要联网,还需要足够的磁盘空间,用于存放恢复镜像以及默认可增长至 64 GiB 的虚拟机磁盘。若要使用内联查看器,需要 Ghostty、Kitty 或 iTerm2;其他终端则会打开原生虚拟机窗口。
现在可以日常使用了吗?还不行:它目前是早期候选版本,构建版本采用自签名,未经 Apple 公证,并且在干净 Mac 上的客机实机验收仍未完成。tmux 直通和自动终端分屏尚未实现。
没有网络还能用吗?首次运行需要联网,从 Apple 获取 macOS,除非你已经有兼容的 .ipsw 文件。之后的运行会复用缓存的镜像和虚拟机。--offline 参数会移除客机网络设备,但共享文件夹控制通道仍然可用。
智能体能访问我的文件、账户和剪贴板吗?不能。客机是一台独立的 Mac,不会继承你正在运行的宿主机应用或已登录的会话,智能体工具也绝不会触碰你自己的桌面。
智能体实际是怎样使用它的?通过 MCP 工具(screenshot、click、drag、scroll、type、key、status)以及一个教智能体遵循“观察-操作-验证”循环的技能。这些工具只驱动客机辅助程序,并告诉智能体客机当前是否停留在登录界面。
我能看到智能体在做什么吗?可以:终端查看器会使用 Kitty 或 iTerm2 的图形协议串流屏幕画面,按 Ctrl+] 可退出查看器,虚拟机则继续运行。按 Ctrl+G 可打开 Mac 快捷操作面板,例如 Spotlight 和 Mission Control。
哪些 AI 工具可以连接它?Claude Code 可以通过同一个插件使用 MCP 服务器和技能,也可以通过 claude mcp add 来使用。Cursor、VS Code、Codex 和 Windsurf 需要使用 terminal-mac mcp --config 的输出内容。任何带有技能文件夹的智能体都可以使用 terminal-mac skills install。
为什么不让智能体直接操控我自己的 Mac?智能体的命令通过客机辅助程序发出,因此不会移动你实际的鼠标指针,也不会更改你的剪贴板。客机拥有自己的应用、文件和账户,与你的数据相互独立。
有哪些类似的项目?arcbox, agentbox, coop, wslmanager, VTCode, tart, nvx, qwen-code
作者
govijr
大小
0.1 MB
星标
2.8K
时长
15天
提交 · 90 天