Repolode
Submit
govijr

govijr/terminal-mac

A macOS virtual machine that AI agents can control through MCP tools, viewed from a terminal via Kitty, Ghostty or iTerm2 graphics.

View on GitHub
Stars
2,228
Forks
145
Open issues
1
Last commit
14 hours ago

What is it?

terminal-mac runs a real macOS guest on Apple silicon using Apple's Virtualization framework. A helper app inside the guest captures the guest's screen and posts keyboard and mouse events, so agents can operate that separate Mac without moving the physical Mac's pointer or touching its clipboard. The guest has its own apps, files and accounts and does not inherit the host's signed-in sessions.

A terminal viewer streams the guest screen inline using Kitty, Ghostty or iTerm2 graphics, and supports typing, clicks, dragging, scrolling and a palette of Mac shortcuts. Agent commands are exposed as MCP tools (screenshot, click, drag, scroll, type, key, status) along with a skill describing an observe-act-verify loop. The CLI handles restore image download, VM creation, booting and lifecycle commands such as pause, resume and stop.

The project is an early release candidate. Guest Screen Recording and Accessibility permissions must be granted interactively during one-time setup, and the VM is not network-isolated by default.

Key features

  • 01Runs a real macOS guest on Apple silicon with its own apps, files and accounts.
  • 02Streams the guest screen inline in Kitty, Ghostty or iTerm2 terminals.
  • 03Exposes screenshot, click, drag, scroll, type, key and status as MCP tools.
  • 04Agent input does not move the host pointer or change the host clipboard.
  • 05Installs with a curl script and downloads the macOS restore image on first run.
  • 06Provides a Ctrl+G palette of Mac shortcuts for keys the terminal cannot send directly.

Use cases

  • Letting an AI agent operate macOS-only apps without taking over your own desktop.
  • Testing macOS GUI software in an isolated virtual Mac.
  • Watching or driving a virtual Mac from a terminal over SSH-free local sessions.
  • Running computer-use agent experiments that need a disposable macOS environment.

Quick start

  1. 1

    Install with the curl installer from the README (verifies SHA-256)

  2. 2

    Run the guided setup to download, install and boot a virtual Mac

    terminal-mac up
  3. 3

    Connect an AI agent through MCP

    claude mcp add terminal-mac -- terminal-mac mcp

Things to know

  • Requires an Apple silicon Mac running macOS 14 or later.
  • Early release candidate; live guest acceptance on a clean Mac is still pending.
  • Releases are self-signed and not notarized by Apple.
  • Inline viewer works only in Ghostty, Kitty or iTerm2.

In collections

Open-source AI agent frameworks & appsMCP serversCLI & terminal toolsOpen-source Mac apps

Topics

#macos#virtualization#computer-use#mcp#ai-agent#terminal#swift#apple-silicon

FAQ

What is terminal-mac?
A macOS virtual machine that AI agents can control through MCP tools, viewed from a terminal via Kitty, Ghostty or iTerm2 graphics. terminal-mac runs a real macOS guest on Apple silicon using Apple's Virtualization framework. A helper app inside the guest captures the guest's screen and posts keyboard and mouse events, so agents can operate that separate Mac without moving the physical Mac's pointer or touching its clipboard. The guest has its own apps, files and accounts and does not inherit the host's signed-in sessions.
Is terminal-mac free to use? What license does it have?
terminal-mac is open source under the MIT license. Check the license terms before using it in commercial products.
Is terminal-mac still maintained?
Actively maintained. The last commit to terminal-mac was on Nov 7, 2026.
What can I use terminal-mac for?
Letting an AI agent operate macOS-only apps without taking over your own desktop. Testing macOS GUI software in an isolated virtual Mac. Watching or driving a virtual Mac from a terminal over SSH-free local sessions. Running computer-use agent experiments that need a disposable macOS environment.
How do I install terminal-mac?
Install with the curl installer from the README (verifies SHA-256) Run the guided setup to download, install and boot a virtual Mac: terminal-mac up Connect an AI agent through MCP: claude mcp add terminal-mac -- terminal-mac mcp
Where can I get terminal-mac?
The source code and installation instructions are on GitHub: https://github.com/govijr/terminal-mac

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects