terminal-mac

Overview

terminal-mac provides a separate macOS desktop for computer-use agents, viewed and controlled from a terminal. It uses Apple Virtualization to run a real macOS guest on Apple silicon, with a helper inside the guest capturing the screen and posting input events. A terminal viewer streams the guest display, and agent commands use the same helper without moving the physical Mac's pointer or changing its clipboard.

Key Features

• Runs a real macOS guest on Apple silicon using Apple Virtualization, separate from the host's apps, files, accounts and permissions.
• Streams the guest screen to Kitty, Ghostty or iTerm2 with an inline terminal viewer, while other terminals can use the native VM window.
• Provides MCP tools for screenshot, click, drag, scroll, type, key and status so agents can observe and act in the guest.
• Routes agent input through a helper inside the guest so commands do not move the host pointer or change the host clipboard.
• Supports guided first-run setup, VM lifecycle commands, and optional user-space networking through gvproxy.
• Includes Claude Code plugin and skill integration plus configuration output for other MCP clients.

Use Cases

• Giving computer-use agents a separate macOS environment for GUI tasks without taking over the user's desktop.
• Testing agent automation against its own apps, files, accounts and permissions inside a virtual Mac.
• Viewing and interacting with a virtual Mac desktop directly from a terminal.
• Running Claude Code or other MCP clients against a virtual Mac through bundled MCP tools and skills.

Getting Started

• Run the latest release installer script, or extract a release ZIP and run bash install.sh.
• Run terminal-mac in an interactive terminal to start the guided flow, or run terminal-mac up explicitly.
• Complete macOS Setup Assistant in the guest, open TerminalMacGuest.app from /Volumes/My Shared Files/tools, and grant Screen Recording and Accessibility inside the guest.
• For Claude Code, install the terminal-mac plugin or add the MCP server with terminal-mac mcp.

Deployment & Requirements

• Apple silicon Mac running macOS 14 or later.
• Internet access on first run to download a compatible macOS restore image from Apple, or an existing compatible .ipsw.
• Space for the cached restore image and a growing VM disk, 64 GiB logical size by default.
• Ghostty, Kitty or iTerm2 for the inline viewer; other terminals can use the native VM window and agent CLI.
• No development tools are needed for a prebuilt release; maintainers need Xcode 16 or later and Swift 6 to build.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• The project is an early release candidate; releases are self-signed and clean-Mac live acceptance is still pending.
• Guest setup is guided and requires interactive macOS setup and permission grants rather than unattended installation.
• Default NAT networking lets the guest reach the internet and may reach services on the host or local network.
• The virtual Mac consumes host CPU, memory and storage.
• The shared folder depends on macOS virtio-fs, and the prototype has no fallback guest transport if it is absent.