Quick Answer: You can run macOS in terminal using terminal-mac, an early release candidate for Apple silicon. It boots a real macOS guest with Apple's Virtualization framework and streams the screen into Kitty, Ghostty or iTerm2. You need macOS 14 or later, a cached restore image, and a one-time guided setup inside the guest. Start with
terminal-mac up.
Most people who want a second macOS environment reach for a full VM manager or a remote desktop app. terminal-mac takes a stranger route: the virtual Mac is drawn inside the terminal you already use, and an agent can drive it from the command line. That's useful, but the details matter. The guest is a separate Mac with its own accounts, and it still uses your host's hardware. Here's what actually happens when you run macOS in terminal this way, and where the rough edges are.
How the pieces fit together
The stack has three layers. Apple Virtualization runs the macOS guest on the host. A bundled guest helper, a small app inside that guest, captures the screen with ScreenCaptureKit and posts input events. A terminal viewer on the host displays those frames using the Kitty or iTerm2 graphics protocols.
The helper doesn't stream video. It keeps a ScreenCaptureKit stream open only while a viewer is watching, and it sends a frame only when the screen changes, up to 30 fps. Frames are already sized to the pixels the terminal draws, and they're lossless lz4-compressed. Kitty and Ghostty receive them through shared memory instead of the pty, which keeps the terminal's byte stream from becoming the bottleneck.
Sizing matters more than most guides admit. A default 1280×800 point display is rendered at 2560×1600 pixels for HiDPI, so text stays sharp on Retina terminals. If you'd rather save pixels, terminal-mac display default --standard switches a stopped VM to a 1x display. Here's the trade-off: 1x costs less work per frame, but small UI text gets soft.
An idle desktop costs almost nothing, because the stream stops 15 seconds after the viewer leaves. The VM itself is never free, though. It still consumes host CPU, memory and storage, and its disk is sparse with a 64 GiB logical default. It grows as the guest writes data.
Installing and the first boot
The install is a single command:
curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash
The installer checks the release's SHA-256 before it installs anything. It puts a launcher in ~/.local/bin, with the runtime under ~/.local/lib/terminal-mac. It needs no administrator rights and doesn't touch your shell configuration, so you add the path yourself if you want to type terminal-mac directly.
The first run does the heavy lifting. terminal-mac up will:
- Download a compatible Apple restore image, or reuse one you already have with
--ipsw. - Install a virtual Mac and boot it.
- Check whether the guest helper is responding.
- Hand you the guest's window to finish setup.
Expect the download to dominate the wait. Packaging can't remove the time needed to fetch and install macOS. If the network drops, URLSession resume data helps, but a hard process kill can force the current download to restart.
The guest setup you can't skip
This is where most people's expectations break. You might assume "one command and done," but terminal-mac is guided setup, not an unattended guest installation. Complete macOS Setup Assistant and create a user account. Then, inside the guest, open Finder → /Volumes/My Shared Files/tools and launch TerminalMacGuest.app once. The helper installs itself into the guest's ~/Applications and registers for future logins, subject to macOS approval.
Next, use the helper's buttons to grant Screen Recording and Accessibility inside the guest. The host needs neither permission, which is deliberate. Once both guest permissions are ready, the CLI moves on to the terminal desktop automatically.
Why does this matter? Because the guest is a separate Mac. It doesn't inherit your signed-in apps, your Keychain or your browser sessions. That's a feature for isolation and a nuisance for setup. As the project's README notes, Apple documents automatic account provisioning for macOS 27 guests, but this build targets the macOS 26 SDK and doesn't implement that flow. Until it does, you're clicking through setup yourself.
Here's the failure mode people hit most. If the guest sits at its login screen, the tools can't see your apps, and they'll say so. The agent is supposed to report that and ask you to sign in, not guess. Keep the guest logged in and the helper running, and approve its login-item setting if macOS asks.
Giving an agent control of the virtual Mac
The useful part of terminal-mac is that an agent can drive the guest without touching your desktop. It exposes MCP tools (screenshot, click, drag, scroll, type, key, status) and a skill that teaches an observe → act → verify loop. Claude Code users can add the server with:
claude mcp add terminal-mac -- terminal-mac mcp
Other MCP clients can use terminal-mac mcp --config. The same actions are available from the shell, as in terminal-mac action default click 640 400.
The obvious alternative is to let an agent run on your own Mac with GUI automation. The table below shows the practical difference.
| Approach | Moves your physical pointer | Shares your clipboard | Uses your signed-in accounts | Setup before first action |
|---|---|---|---|---|
terminal-mac guest (terminal-mac mcp) | No, the helper posts events inside the guest | No | No, the guest has its own accounts | Guided setup and two guest permissions |
| Agent automating your own Mac | Yes, it drives your real desktop | Yes | Yes | Host Accessibility and Screen Recording grants |
| Remote desktop session to a second Mac | Depends on the client and server setup | Often, depending on configuration | Depends on what you sign into | Remote access enabled on the target |
The table makes one point clear: the guest is the safer blast radius, but it's also a blank machine. You'll need to plan your agent's tasks around that. That said, a blank machine is exactly what you want when you're letting software click things.
Terminal support, shortcuts and the Ctrl+G palette
The inline viewer works in Ghostty, Kitty and iTerm2. Other terminals can still use the native VM window and the agent CLI, but they won't show the stream inline. tmux passthrough and automatic terminal splits are not implemented, so if your workflow lives inside tmux, expect to run the viewer in its own window.
Keyboard input is where terminals fight you. Terminals keep ⌘ for themselves, so the viewer can't send Command shortcuts directly. Press Ctrl+G to open a palette of Mac shortcuts for Spotlight, Mission Control, copy and paste, close and quit. Press Ctrl+] to leave the viewer while the VM keeps running. Closing the native VM window hides it and also leaves the VM running. Most people expect closing a window to stop a VM, so this is worth remembering.
Mouse support covers left and right clicks, double and triple clicks, dragging and scrolling. Arrow keys and common control keys work too.
Isolation, resources and the parts that aren't finished
Isolation has a clear boundary, and it's narrower than the phrase "separate machine" suggests. The guest doesn't share your apps or sessions, and the host's screen and input APIs aren't used for agent actions. The helper refuses to run unless hw.model starts with VirtualMac, which prevents accidental execution on your real Mac. That check is a guardrail, though. It is not hardware attestation, and it doesn't defend against a compromised host.
Releases are self-signed and not notarized by Apple. The curl installer verifies SHA-256, but you're still trusting the release channel. Live guest acceptance on a clean Mac is also still pending, so treat this as an early release candidate.
The MCP tools have limits too. snapshot is a screenshot alias, not an accessibility-tree snapshot, so an agent works from pixels rather than from UI structure. Agents using screenshots need to verify each action, which is why the observe → act → verify loop matters. The --offline flag omits the guest network device, and some setup workflows may need networking, so it's not a free way to lock things down.
There's also no destructive VM-delete command yet. A failed installation keeps its directory and installed: false for diagnosis. To retry, make sure nothing is running, move the incomplete directory aside, and create the VM again.
Frequently Asked Questions
what is terminal-mac?
terminal-mac is an early release candidate for Apple silicon Macs that runs a real macOS guest with Apple Virtualization and displays its screen in a terminal. It uses a guest helper for screen capture and input, and it exposes MCP tools so AI agents can operate the virtual Mac. It requires macOS 14 or later and works best in Ghostty, Kitty or iTerm2.
how do i run macos in terminal on my own mac?
Run the curl installer, then execute terminal-mac up. The command downloads a compatible restore image, installs a virtual Mac and boots it. Finish macOS Setup Assistant, launch the helper from the shared tools folder inside the guest, and grant Screen Recording and Accessibility there. The host viewer then connects automatically.
why does terminal-mac say the guest is at the login screen?
The tools can only see the guest's desktop when a user is logged in and the helper is running. At the login screen, screenshots and input can't reach your apps, so the tools report that state. Sign in inside the guest, keep it logged in, and make sure the helper is running. Then retry the action.
does running a virtual Mac use my host's resources?
Yes. The VM uses host CPU, memory and storage while it runs. The disk is sparse with a 64 GiB logical default, so it grows as the guest writes data. The screen stream only runs while a viewer is connected and stops 15 seconds after the viewer leaves, so an idle desktop costs little.
Start with one VM this week
The most useful way to evaluate terminal-mac is to run terminal-mac up on a machine you can afford to experiment on, complete the guest setup once, and take a screenshot with terminal-mac action default screenshot. Only then decide whether your agent workflow belongs in a separate Mac. Pass this to someone wrestling with the question of how to run macOS in terminal without touching their own desktop.