What Is terminal-mac? The Beginner's Guide to Running a Virtual macOS in Your Terminal

CodexFuse Team · 2026-11-05T08:09:03.769Z · 22 min read min read

What Is terminal-mac? The Beginner's Guide to Running a Virtual macOS in Your Terminal

What Is terminal-mac?

If you have asked what is terminal-mac, the short answer is that it is a free, open-source tool that boots a real macOS guest inside your terminal and hands that guest to an AI coding agent. The agent clicks, types, and takes screenshots inside the virtual Mac while your own desktop, files, and signed-in sessions stay untouched. The project calls the idea simple: give your agent its own Mac, and keep yours.

terminal-mac is an early release candidate from developer govijr, published on November 3, 2026, and it already has more than 1,700 GitHub stars two days later. It is built for developers who let agents such as Claude Code or Codex use a computer, and who do not want that agent wandering around their real desktop. The guest is a separate Mac with its own apps, files, accounts, and permissions, and it does not inherit your host apps or your signed-in sessions.

Installing it takes one curl command, and the installer checks a SHA-256 hash before it installs anything, which is the same kind of check a SHA-256 hash generator performs on a file. The tool is aimed at Mac developers first, and it only runs on Apple silicon. If you run agents on a server instead of a laptop, the same isolation instinct applies to VPS hosting, where each project gets its own machine instead of sharing yours.

How Does terminal-mac Work Under the Hood?

terminal-mac is a Swift app built on Apple Virtualization, the framework Apple provides for running guest operating systems on Apple silicon. The terminal-mac apple virtualization layer is what makes the guest a real Mac instead of a simulation. It boots a genuine macOS guest rather than a container or a remote desktop, so the agent works with a real Mac desktop, a real Dock, and real Mac apps.

The native Virtualization framework does not itself render a Mac into a terminal or offer an agent input API, so this project supplies both the guest transport and the terminal presentation layers.

A small helper app runs inside the guest and does two jobs. It captures the guest screen and posts input events into it, and it is the only thing the agent talks to. The agent never reaches your physical Mac pointer, keyboard, clipboard, or screen APIs, because every action flows through that helper.

The helper refuses to run unless the hardware model starts with VirtualMac, a check that stops accidental execution on your own Mac.

The viewer is what makes the tool feel different. The guest screen streams into your terminal using the Kitty graphics protocol or iTerm2 inline images, so the virtual Mac sits inline in Ghostty, Kitty, or iTerm2 next to your shell. In any other terminal you get a normal VM window instead, and the agent CLI still works.

The helper keeps a ScreenCaptureKit stream open while a viewer is watching, and it sends a frame only when the screen changes, at up to 30 frames per second, already sized to the pixels the terminal draws, as lossless lz4-compressed pixels. An idle desktop costs nothing, and the stream stops 15 seconds after the viewer leaves.

Host and guest communicate through a shared folder, not a network listener. The guest sees two explicit shares: a read-write control share that carries request and reply JSON plus screenshots, and a read-only tools share that holds the helper app. The mailbox pins its directory, rejects symlinks, hardlinks, and non-regular files on reads, bounds message sizes, checks request IDs, and expires pending actions.

Your host home folder, project folders, clipboard, microphone, and camera are not attached to the guest at all.

What Do You Need Before You Install terminal-mac?

The requirements are short, and the tool checks them for you, but it helps to know them before the first download starts. The first boot downloads a macOS restore image from Apple, which is several gigabytes, so a fast connection and free disk space matter more than anything else. The table below lists every requirement from the project README.

One detail catches new users by surprise. The guest setup is guided, not unattended, so plan for a few minutes of clicking inside the guest on your first run. Apple documents automatic account provisioning for macOS 27 guests, and this build does not implement that newer flow yet.

You will create the guest account yourself, exactly as you would on a new Mac.

How Do You Install terminal-mac?

The terminal-mac install takes five steps, and only the first boot is slow, because that is when macOS itself downloads and installs. The whole flow is designed to be run once and then forgotten, since later runs reuse the existing virtual Mac and reconnect to it.

1. Check that you are on an Apple silicon Mac running macOS 14 or later, in Ghostty, Kitty, or iTerm2 if you want the inline viewer.
2. Run the installer, which downloads the latest release, verifies its SHA-256, and places one launcher in your local bin folder and the runtime under your local lib folder, with no administrator rights and no changes to your shell configuration.
3. Run terminal-mac up, which downloads a compatible macOS restore image from Apple, installs the virtual Mac, boots it, and checks the guest helper.
4. Complete the one-time guest setup inside the guest, including its two privacy permissions, as described in the next section.
5. Connect your agent through the plugin or MCP server, then ask it to take a screenshot and describe what it sees.

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

The installer needs no administrator rights and does not edit your shell configuration. You can also extract a release ZIP and run bash install.sh from it, or pass bash install.sh --prefix with an absolute path to choose another location. Add your local bin folder to your PATH to use the plain terminal-mac command.

A second machine is one command away, since terminal-mac up work creates another virtual Mac, and terminal-mac up --ipsw with a local image path skips the download when you already have a restore image.

What Happens on Your First Boot?

The first run opens the virtual Mac window, and you complete macOS Setup Assistant there and create the guest user account. This is the guided part, and it is the only part the tool does not automate. Inside the guest, open Finder, go to the shared tools volume, and open TerminalMacGuest.app once.

The helper installs itself in the guest Applications folder, launches that installed copy, and registers for future guest logins, subject to macOS approval.

The helper has two buttons for the permissions it needs, Screen Recording and Accessibility, granted inside the guest own System Settings. Your host Mac needs neither permission, which is the point of the whole design. Reopen the helper if macOS asks, and use its Guest Login Items button if needed to open the startup setting.

Once both guest permissions are ready, the CLI automatically continues to the terminal desktop.

New virtual machines use a 2x HiDPI display by default, for example 2560 by 1600 pixels at 220 pixels per inch for a 1280 by 800 point desktop, so text stays sharp on Retina terminals. That is four times the pixels of the same desktop at 1x, since each dimension doubles. You can switch a stopped VM with terminal-mac display default --hidpi or --standard.

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

How Do You Use terminal-mac With an AI Agent?

This section explains how to use terminal-mac with an AI agent, and it runs through an MCP server plus a skill that teaches the observe, act, verify loop. The MCP server exposes seven tools, and the skill tells the agent how to use them in order: look at the screen, take one action, then look again to check the result. The table below lists every tool the server offers.

For Claude Code, the project ships one plugin that installs both the MCP server and the skill. Run the plugin command inside Claude Code, and the agent can drive the guest immediately. Our how to use Claude Code guide covers the agent itself if you have not used it before.

For other MCP clients such as Cursor, VS Code, Codex, or Windsurf, paste the output of terminal-mac mcp --config into the client MCP settings, and use terminal-mac mcp NAME for a VM other than the default one.

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

You can also add the server and the skill separately with two commands, or give any agent with a skills folder the same instructions by installing the skill into that folder. The skill advice is the same loop you would give an agent by hand: open apps with command and space, type the name, press return, and take a fresh screenshot after each step that mattered. The tools only drive the guest helper, never your own desktop, and when the guest is at its login screen they say so, so the agent can ask you to sign in.

Which terminal-mac Commands Will You Actually Use?

Day to day, terminal-mac is a small set of lifecycle commands plus the action commands that drive the guest. Commands return JSON and a nonzero exit status on failure, which makes them easy to script or read in a log. Screenshots return a local host PNG path, and coordinates start at the top-left and match the screenshot dimensions, using guest display points so the same numbers work on Retina displays.

Custom sizing is set when you create a machine, with options such as --cpus 4 --memory 4 --disk 64 --width 1280 --height 800, where CPU, memory, and disk are logical CPUs and gibibytes. The viewer supports typing, left and right clicks, double and triple clicks, dragging, scrolling, arrows, and common control keys. Control and G opens a palette of Mac shortcuts such as Spotlight, Mission Control, copy and paste, and close and quit, because terminals keep the Command key for themselves, and Control and right bracket exits the viewer while the VM keeps running.

Closing the native VM window hides it and also leaves the VM running.

VM data lives in your Library Application Support folder under terminal-mac machines, with one directory per machine holding a sparse disk, hardware identity, auxiliary boot storage, machine settings, a private host-control mailbox, the guest exchange directory, and a runtime log. A VM boot runs as a separate background process, and lifecycle commands must use the same data root as the process that started it. An interrupted or failed installation leaves its directory marked as not installed for diagnosis, and it is never silently overwritten, so you move that incomplete directory aside and create the VM again.

terminal-mac vs Lume: Which One Fits Your Job?

Lume is the closest comparison, and it is the other half of the terminal-mac vs Lume question. Lume is Cua tool for creating and running macOS and Linux virtual machines on an Apple silicon Mac, also built on Apple Virtualization, and also free and open source. The difference is the job each tool is built for: terminal-mac puts the virtual Mac inside your terminal and gives an agent computer control of it, while Lume is for managing the VMs yourself, with SSH, an HTTP API, and MCP tools for starting and stopping them.

The table below compares the two, with Cua Driver and Quickemu alongside them.

The disk numbers tell a small story on their own. A terminal-mac default disk of 64 gibibytes is about 68.7 gigabytes, which is roughly 31 percent smaller than Lume 100 gigabyte default, so a terminal-mac guest starts lighter even before you count the cached restore image. Lume defaults are 4 CPUs, 8 GB of memory, and a 100 GB disk, and it allows up to two macOS guests at a time, which is Apple limit.

If you need a Linux guest at all, Lume is the only one of the two that offers it, though its Linux guide is marked experimental. Our Quickemu beginner guide covers the Linux-side equivalent, a QEMU wrapper that downloads and boots whole operating systems with two commands, and it is the published sibling of this article rather than a rival.

terminal-mac vs Cua Driver: Sandbox or Background Control?

The terminal-mac cua driver question is really a choice between two kinds of help, and the two can both be true for the same developer. Cua Driver lets AI agents like Claude Code and Codex use the apps on your own computer, clicking, typing, and reading in windows behind yours, with a cursor of their own, so your pointer and keyboard stay yours. It reads each system accessibility tree, so agents can work in native apps like spreadsheets and settings as well as web pages, on Mac, Windows, and Linux.

It is open source, MIT licensed, and free, and it connects through MCP or the command line.

The trade is isolation against convenience. With Cua Driver, the agent works on your real desktop, which means it can reach your real files, your real browser tabs, and your real signed-in sessions, and you keep working alongside it. With terminal-mac, the agent works on a disposable Mac that shares nothing with your desktop, and you watch it in a terminal pane.

That is why the mlllm.io coverage pairs the two tools and suggests supplementing the sandbox with Cua Driver, using the accessibility tree where precise interface interaction helps. Note that mlllm.io is an AI-content aggregator, not an independent review, so treat its framing as a pointer to the two projects rather than a tested verdict.

One claim in that coverage deserves care. The aggregator piece suggests the accessibility tree might beat vision-only screenshots on efficiency, but it also states that no quantitative measurement supports the claim, with no token usage, click accuracy, or latency figures anywhere in its sources. No published measurement compares token cost between the two approaches, so choose between them on isolation and workflow, not on an unmeasured efficiency claim.

What Does the Isolation Really Protect, and What Does It Not?

The isolation model is the strongest part of terminal-mac, and also the part most worth reading carefully, because it protects some things completely and others not at all. The guest is a separate Mac, so an agent cannot open your email, read your password manager, or click through a bank tab on your real desktop. It cannot see your clipboard, your microphone, or your camera, and it cannot reach your project folders, since none of those are attached to the guest.

The host never executes guest-provided content, and there is no remote-control network listener for anyone to connect to.

Networking is the weak spot, and the README says so plainly. Default NAT networking gives the guest internet access and may let it reach services on your host or local network, so this is not a network-isolated or hardened hostile-code environment. If the guest needs no network at all, the --offline flag removes the guest network device, though the shared-folder control channel still works and some macOS setup workflows may require networking.

A locked or logged-out guest, a missing helper, denied guest permissions, or a paused VM all prevent normal computer use, and the privacy grants are interactive guest setup, not bypassed by the CLI.

Think of it as a disposable Mac, not a prison. It keeps an agent out of your desktop, your session cookies, and your files, but it does not turn the guest into a sandbox for code you already believe is malicious. An email sent or a purchase made from the guest is still real, and the guest still spends your host CPU, memory, and storage while it runs, so pause it when you are not using it.

The isolated macOS sandbox terminal pattern is about lowering the cost of a mistake, not removing the need for judgment.

What Are the Early-Release-Candidate Caveats?

terminal-mac is two days old as of this writing, and its README is honest about that. Version 0.2.0-6, released November 3, 2026, is an early release candidate, and live guest acceptance on a clean Mac is still pending, which means the project authors have not yet confirmed a full install on a fresh machine. Releases are self-signed with no Apple notarization, which the curl installer does not need, but you are trusting an unsigned build either way.

Keep backups of anything important before you let an agent loose in the guest, since there is deliberately no destructive VM-delete command yet and version control and rollbacks remain your responsibility.

The missing pieces are listed as future work rather than hidden. VM cloning, rollback checkpoints, accessibility snapshots, fully unattended guest setup, terminal splits, and tmux transport all remain to be built. The snapshot command today is a screenshot alias, not an accessibility-tree snapshot, so do not expect it to return interface structure.

The growth around the project is fast, with stars rising from about 1,136 on November 4 to about 1,700 on November 5, a gain of 564 stars, or roughly 50 percent, in about a day, and 101 forks alongside them, or about 17 stars per fork. Nine commits in the first two days is about four or five a day, which is the pace of a project still being shaped in public.

None of that makes the tool unusable, and it does make the version you install worth checking. Features, defaults, and even the install flow can change quickly at this stage, so verify the current release on the project page before you follow any guide, including this one. The sibling project terminal-phone does the same thing for iOS simulators and real iPhones, if your agent work lives on a phone screen instead of a Mac desktop.

Who Should Use terminal-mac, and Who Should Wait?

terminal-mac fits developers who give agents computer-use tasks on a Mac and want those tasks fenced off from their real desktop. If your agent has to test a Mac app, walk through a website as a signed-out user, or try a flow you do not want in your own account, a separate Mac is the straightforward answer. It also fits anyone who already lives in Ghostty, Kitty, or iTerm2 and wants the guest screen in the same window as their shell, rather than in a separate app.

Wait if you are on an Intel Mac, on Windows or Linux, or if you need unattended provisioning, VM snapshots, or cloning today, since those are all future work. If your agents only run code and never need a graphical desktop, a cloud sandbox is a better fit, and our how to use E2B guide covers that pattern, where each agent gets an isolated Linux sandbox in the cloud instead of a Mac on your desk. If your agent needs to work in your real apps while you keep working, Cua Driver is the better tool, because terminal-mac deliberately gives the agent a different Mac, not yours.

The safest first run is a small one. Install it, boot the default machine, do the guest setup, connect Claude Code, and ask the agent to take a screenshot and describe what it sees. Then ask it to open Safari and load a page, and watch the frames arrive in your terminal.

If that loop feels right, the guest is ready for real work, and your own Mac never had to be part of the experiment.

Sources

terminal-mac README, govijr/terminal-mac on GitHub, fetched November 5, 2026, including the requirements, install steps, MCP tools, lifecycle commands, and isolation model. Flavio Copes, terminal-mac: give your computer-use agent its own Mac, flaviocopes.com, November 4, 2026. iPhoneWired, Mac tip: install terminal-mac and give coding agents an isolated macOS VM, November 4, 2026.

mlllm.io, terminal-mac and Cua Driver: An Isolated macOS Sandbox for Terminal AI Agents, November 2026. Cua Driver product page, cua.ai/cua-driver, fetched November 5, 2026. Lume documentation, cua.ai/docs/lume, read November 5, 2026, including the quickstart, HTTP API reference, how Lume works, and Linux guests guide.

Frequently Asked Questions

Is terminal-mac free?

Yes. terminal-mac is MIT licensed and free, with no paid tier and no price listed anywhere on the project page. The only cost is your own Mac resources, since the guest uses host CPU, memory, and storage while it runs, plus the disk space for the cached macOS restore image and the sparse VM disk.

Does terminal-mac work on Intel Macs?

No. terminal-mac needs an Apple silicon Mac running macOS 14 or later, because it builds on Apple Virtualization, which only runs macOS guests on Apple silicon. Intel Mac users, and Windows and Linux users, should look at Lume only if they have an Apple silicon host, or at cloud sandboxes and desktop VM tools for their own platform.

Can an agent using terminal-mac see my real desktop or files?

No. The agent only drives the guest helper inside the virtual Mac, and it never touches your host pointer, keyboard, clipboard, or screen. The guest has its own apps, files, accounts, and permissions, and your host home folder, project folders, clipboard, microphone, and camera are not attached.

The one exception is networking, since default NAT gives the guest internet access and a path toward host or local-network services, so use the offline flag when the guest needs no network.

How do I delete a terminal-mac virtual machine?

There is no delete command yet, deliberately, so nothing is ever destroyed by accident. To remove a machine, stop it, then move its directory aside from the machines folder under Library Application Support, and create a new VM if you need one. Keep backups first, since an interrupted installation is never silently overwritten and must be moved aside before you retry.

Should I use terminal-mac or Lume?

Use terminal-mac when the agent needs a whole disposable Mac with a screen it can click and type into, shown inside your terminal. Use Lume when you want to manage macOS or Linux virtual machines yourself, with SSH access, an HTTP API, unattended setup presets, and clone and delete commands. The two tools share Apple Virtualization and the same restore images from Apple, so the choice is about the workflow, not the virtualization underneath.