terminal-mac CLI
terminal-mac boots a separate guest macOS in Apple's built-in virtualization and hands it to an agent for computer-use tasks.
- 2,693 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- An agent gets control of a separate virtual machine: screen capture and input events inside the guest run through a bundled helper.
Install
- Works in
Manual install
curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bashThe script downloads the latest release and verifies its SHA-256 before installing.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- An agent gets control of a separate virtual machine: screen capture and input events inside the guest run through a bundled helper.
This is third-party code. Review the repository files before installing.
What it does
terminal-mac boots a real guest macOS through Apple Virtualization directly on an Apple Silicon Mac and hands it over to agents that work with a computer directly. A bundled helper inside the guest captures its screen and relays input events; a terminal viewer streams that screen using Kitty or iTerm2 graphics, and agent commands go through the same helper, without moving the host Mac's pointer or touching its clipboard. The guest is a fully separate Mac: its own apps, files, accounts and permissions, with no inheritance of the host's running programs or signed-in sessions. The VM still consumes the host's CPU, memory and disk space.
Who it is for. Computer-use agent developers on Apple Silicon who need an isolated macOS sandbox, viewable and controllable right from a terminal.
Good fit when
- An agent needs a full macOS to work with, but no access to the host machine's accounts and files.
- Watching and controlling the guest system's screen needs to happen right from Kitty or iTerm2, with no separate GUI window.
- Agent commands need to go through the same channel as screen capture, without moving the host's cursor as a side effect.
- Automation testing needs a clean system that inherits none of the host Mac's sessions.
Not a fit when
- The Mac is not Apple Silicon: Apple Virtualization specifically needs that processor.
- The terminal is not Ghostty, Kitty or iTerm2: the inline screen viewer only works through their graphics protocols, other terminals get the native VM window instead.
- tmux passthrough or automatic terminal splitting is needed: the author explicitly states it is not implemented.
Example request
Boot the guest macOS, open its settings app and check it has no visibility into my accounts from the main machine.Limitations
An Apple Silicon Mac with macOS 14 or newer is required. The first run needs internet access to download the macOS image directly from Apple, or an already-available compatible `.ipsw` file. The virtual disk grows to a 64 GiB logical size by default, plus space for the cached restore image, and all of it draws on the host's CPU, memory and storage. Inline screen viewing only works in Ghostty, Kitty or iTerm2; other terminals get the native VM window and the agent CLI, but no tmux passthrough or automatic splitting.
How to disable. Stop and delete the guest virtual machine through the project's own CLI, then remove the installed release itself.
FAQ
Can the guest system see my passwords from the main Mac?
No, the guest inherits no running apps or signed-in sessions from the host; its own accounts and permissions start from scratch.
Are developer tools needed to install it?
No for a prebuilt release; Xcode 16 or newer and Swift 6 are only needed to build the project yourself.
How does an agent control the guest system?
Through the same bundled helper inside the guest that captures its screen; this never moves the host Mac's cursor or touches its clipboard.
How much disk space does the VM use?
The disk grows to a 64 GiB logical size by default, plus a cached restore image, both drawing on host storage.
Does inline viewing work in any terminal?
No, only in Ghostty, Kitty or iTerm2; other terminals get the native VM window and the agent CLI instead.
Discussion
No questions or reviews yet.
Related
CLI toolsA native macOS terminal built on Ghostty with vertical tabs and notifications when an agent needs your input
A native Mac app with a bundled MCP server that lets an agent manage Docker containers locally and over SSH.
An agent guides a macOS install on an ordinary Windows PC: it checks hardware, prepares a USB drive and keeps Windows.
clawk is a virtual-environment CLI that snapshots a Linux machine’s memory and disk so running processes can be resumed later.
Open Terminal gives AI agents a computer of their own with a REST API: shell, files, code, browser and desktop
devvm gives each project its own virtual machine with the right toolchains, where Claude Code and Codex cannot see your secrets
README in short
The project is described as an early release candidate built specifically for Apple Silicon, with its main scenario aimed at computer-use agents rather than a person at a GUI.