Skip to content
Back to search

terminal-mac

MarketplaceWorks with Claude CodeGitHub

Entire MacOS running in your terminal.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/govijr--terminal-mac/badge.svg)](/listings/govijr--terminal-mac)

HTML

<a href="/listings/govijr--terminal-mac"><img src="/api/listings/govijr--terminal-mac/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

The installer downloads the latest release and verifies its SHA-256 before installing. You can also extract a release ZIP and run `bash install.sh` from it.

The installer places one launcher in `~/.local/bin` and the bundled runtime under `~/.local/lib/terminal-mac`. Add `~/.local/bin` to your PATH to use simply `terminal-mac`. It needs no administrator rights and does not edit your shell configuration. `bash install.sh --prefix /absolute/path` selects another location.

Running `terminal-mac` in an interactive terminal starts the guided flow. `terminal-mac up` does the same explicitly. It automatically downloads/caches a compatible Apple restore image, installs a virtual Mac, boots it and checks the guest helper. Later runs reuse the existing VM and reconnect. Unsupported terminals get the native desktop window.

**Current status:** early release candidate. Releases are self-signed (no Apple notarization), which the curl installer doesn't need. Live guest acceptance on a clean Mac is still pending.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "terminal-mac",
  3. "owner": {
  4. "name": "Govijr",
  5. "url": "https://github.com/govijr"
  6. },
  7. "metadata": {
  8. "description": "Computer use in a separate virtual Mac for coding agents."
  9. },
  10. "plugins": [
  11. {
  12. "name": "terminal-mac",
  13. "source": "./",
  14. "description": "Computer use in a separate virtual Mac, with MCP tools and an agent skill."
  15. }
  16. ]
  17. }
README.md · README · 202 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # terminal-mac
  2. [![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/govijr)
  3. <a href="https://buymeacoffee.com/govijr" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 21px !important;width: 108px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></a>
  4. A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.
  5. `terminal-mac` is an early release candidate for Apple silicon. Apple Virtualization runs a real macOS guest. A bundled helper **inside that guest** captures its screen and posts input events. A terminal viewer streams that screen using Kitty or iTerm2 graphics. Agent commands use the same helper without moving the physical Mac's pointer or changing its clipboard.
  6. The guest is a separate Mac: it has its own apps, files, accounts and permissions. It does not inherit your running host apps or signed-in sessions. The VM still consumes host CPU, memory and storage.
  7. ## Requirements
  8. - Apple silicon Mac, macOS 14 or later.
  9. - No development tools are needed for a prebuilt release. Maintainers need Xcode 16 or later / Swift 6 to build.
  10. - Internet on first run to download macOS directly from Apple, or an existing compatible `.ipsw`.
  11. - Space for the cached restore image and a growing VM disk (64 GiB logical size by default).
  12. - Ghostty, Kitty or iTerm2 for the inline viewer. Other terminals can use the native VM window and agent CLI. tmux passthrough and automatic terminal splits are not implemented.
  13. ## Install and run
  14. ```sh
  15. curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash
  16. ```
  17. The installer downloads the latest release and verifies its SHA-256 before installing. You can also extract a release ZIP and run `bash install.sh` from it.
  18. The installer places one launcher in `~/.local/bin` and the bundled runtime under `~/.local/lib/terminal-mac`. Add `~/.local/bin` to your PATH to use simply `terminal-mac`. It needs no administrator rights and does not edit your shell configuration. `bash install.sh --prefix /absolute/path` selects another location.
  19. Running `terminal-mac` in an interactive terminal starts the guided flow. `terminal-mac up` does the same explicitly. It automatically downloads/caches a compatible Apple restore image, installs a virtual Mac, boots it and checks the guest helper. Later runs reuse the existing VM and reconnect. Unsupported terminals get the native desktop window.
  20. **Current status:** early release candidate. Releases are self-signed (no Apple notarization), which the curl installer doesn't need. Live guest acceptance on a clean Mac is still pending.
  21. ## Use with agents
  22. terminal-mac gives agents computer use in a separate virtual Mac, through MCP tools (`screenshot`, `click`, `drag`, `scroll`, `type`, `key`, `status`) and a skill that teaches the observe → act → verify loop.
  23. **Claude Code**, with the MCP server and skill in one plugin:
  24. ```text
  25. /plugin install terminal-mac --marketplace govijr/terminal-mac
  26. ```
  27. Or add them separately:
  28. ```sh
  29. claude mcp add terminal-mac -- terminal-mac mcp
  30. terminal-mac skills install # → ~/.claude/skills/terminal-mac/SKILL.md
  31. ```
  32. **Other MCP clients** (Cursor, VS Code, Codex, Windsurf…): paste the output of `terminal-mac mcp --config` into the client's MCP settings. Use `terminal-mac mcp NAME` for a VM other than `default`.
  33. **Any agent with a skills folder:** `terminal-mac skills install --dir PATH`, or `npx skills add govijr/terminal-mac --skill terminal-mac`. In an `AGENTS.md`, a line like "Before using the virtual Mac, run `terminal-mac skills get`" gives the agent instructions that match the installed version.
  34. The tools only drive the guest helper. They never touch your own desktop. When the guest is at its login screen, they say so, so the agent can ask you to sign in.
  35. ## One-time guest setup
  36. The first run opens the virtual Mac's window. Complete macOS setup and create its user account. Inside the guest, open Finder → `/Volumes/My Shared Files/tools` → `TerminalMacGuest.app` once. The helper installs itself in the guest's `~/Applications`, launches that installed copy and registers for future guest logins, subject to macOS approval.
  37. Use its two buttons to grant **Screen Recording** and **Accessibility** inside the guest. Reopen it if macOS asks. If needed, its **Guest Login Items** button opens the startup setting. The host needs neither privacy permission. Once both guest permissions are ready, the CLI automatically continues to the terminal desktop. From then on the helper lives as a computer icon in the guest's menu bar: it opens at login without showing a window, the icon's menu shows the permission state, and **Open Setup Window…** brings the window back.
  38. This is guided setup, not an unattended guest installation. Apple documents automatic account provisioning for macOS 27 guests; this build targets the APIs available in the installed macOS 26 SDK and does not implement that newer flow. See [Apple's provisioning documentation](https://developer.apple.com/documentation/virtualization/vzmacguestprovisioningoptions).
  39. ```sh
  40. terminal-mac up work # another virtual Mac
  41. terminal-mac up --ipsw /path/mac.ipsw # use a local image
  42. terminal-mac up --no-view # wait for agent readiness, then return JSON
  43. terminal-mac up --detach # install/boot, return without waiting for guest setup
  44. terminal-mac up --plan # show steps without network access or disk changes
  45. ```
  46. The first download may take time; packaging cannot eliminate downloading and installing macOS. The image cache is reused, and URLSession resume data is retained after recoverable network failures. A hard process kill may require the current download to restart. An incomplete installation with recorded hardware can be retried by `up` using a compatible restore image; an already installed VM is never reinstalled by `up`.
  47. ## Build from source
  48. ```sh
  49. bash scripts/build.sh
  50. ./dist/terminal-mac doctor
  51. ```
  52. The build creates `dist/TerminalMac.app`, including `TerminalMacGuest.app`, and the `dist/terminal-mac` launcher. Virtualization needs the host executable's `com.apple.security.virtualization` entitlement; use the packaged launcher instead of the unsigned Swift build product.
  53. It is signed with the self-signed "Govijr Code Signing" identity when your keychain has it (`bash scripts/create-signing-identity.sh` makes one), and ad-hoc otherwise. A stable identity keeps the guest helper's permissions across rebuilds; ad-hoc builds need them granted again. [RELEASING.md](RELEASING.md) covers signing and publishing.
  54. ## Create your first Mac
  55. ```sh
  56. # Show the URL and version without downloading anything:
  57. ./dist/terminal-mac image
  58. # Explicitly download Apple's latest supported restore image (several GB):
  59. ./dist/terminal-mac image --output /tmp/RestoreImage.ipsw
  60. # Install macOS. The disk is sparse, and the IPSW is not copied into the VM bundle.
  61. ./dist/terminal-mac create default --ipsw /tmp/RestoreImage.ipsw
  62. ./dist/terminal-mac start default --window
  63. ```
  64. Complete macOS Setup Assistant in the VM window and create a guest account. Inside the guest:
  65. 1. Open Finder → `/Volumes/My Shared Files/tools`.
  66. 2. Open `TerminalMacGuest.app`. It installs itself to the guest's `~/Applications` and opens the installed copy.
  67. 3. Use the helper's buttons to grant **Screen Recording** and **Accessibility** in the guest's System Settings. Reopen the helper if macOS asks. The host does not need either permission.
  68. If both toggles are on but `terminal-mac action NAME status` still reports `false`, for example after a helper signed with a different identity replaced the one that was approved, run `terminal-mac action NAME permissions`. It clears the stale grants inside the guest and prompts again.
  69. 4. Keep the guest logged in and the helper running. It registers itself for guest login; approve that setting if macOS requests it.
  70. On the host:
  71. ```sh
  72. ./dist/terminal-mac action default status
  73. ./dist/terminal-mac hide default
  74. ./dist/terminal-mac view default
  75. ```
  76. The viewer supports typing, left/right clicks, double and triple clicks, dragging, scrolling, arrows and common control keys. **Ctrl+G** opens a palette of Mac shortcuts (Spotlight, Mission Control, copy/paste, close/quit and more), because terminals keep ⌘ for themselves. **Ctrl+]** exits the viewer while the VM keeps running. Closing the native VM window hides it and also leaves the VM running.
  77. The guest helper keeps a ScreenCaptureKit stream open while a viewer is watching. It sends a frame only when the screen changes (up to 30 fps), already sized to the pixels the terminal draws, as lossless lz4-compressed pixels. Kitty and Ghostty receive those frames through shared memory rather than the pty. An idle desktop costs nothing, and the stream stops 15 seconds after the viewer leaves. From build 4 on, the guest helper updates itself: within 30 seconds of a newer build appearing in the shared tools folder, it installs that build and relaunches. Helpers from build 3 and earlier still work but poll full screenshots, and the header shows "snapshots". Update those once by opening `/Volumes/My Shared Files/tools/TerminalMacGuest.app` in the guest. Releases are signed with one unchanging self-signed certificate, so the guest keeps its Screen Recording and Accessibility approvals across updates.
  78. Guest helper updates must satisfy the running helper's designated code requirement. Stable certificate-signed builds retain their update identity. An ad-hoc rebuild generally has a different code identity and is refused by automatic updates; install it manually inside the guest and grant its permissions again.
  79. Agents can drive the guest through an MCP server: `claude mcp add terminal-mac -- "$PWD/dist/terminal-mac" mcp default`. See [docs/AGENT.md](docs/AGENT.md).
  80. New VMs use a 2x HiDPI display (for example 2560×1600 pixels at 220 ppi for the default 1280×800 points), so text stays sharp on Retina terminals. Switch a stopped VM with `terminal-mac display default --hidpi` or `--standard`.
  81. The automounted volume is supplied by macOS virtio-fs. If it is absent, check the guest's macOS version and the VM log; this prototype has no fallback guest transport.
  82. ## Give an agent computer control
  83. ```sh
  84. ./dist/terminal-mac action default screenshot --output /tmp/guest.png
  85. ./dist/terminal-mac action default click 640 400
  86. ./dist/terminal-mac action default type 'Hello from the agent'
  87. ./dist/terminal-mac action default key cmd+space
  88. ./dist/terminal-mac action default key return
  89. ./dist/terminal-mac action default scroll --dy -300 --x 640 --y 400
  90. ```
  91. Commands return JSON and a nonzero exit status on failure. Screenshots return a local host PNG path. Coordinates start at the top-left and match the screenshot's dimensions; screenshots use guest display points to keep input coordinates consistent on Retina displays. `snapshot` is currently a screenshot alias, not an accessibility-tree snapshot.
  92. The agent instructions are in [docs/AGENT.md](docs/AGENT.md). No global agent settings are modified.
  93. ## Lifecycle and resources
  94. ```sh
  95. ./dist/terminal-mac ls
  96. ./dist/terminal-mac status default
  97. ./dist/terminal-mac pause default
  98. ./dist/terminal-mac resume default
  99. ./dist/terminal-mac show default
  100. ./dist/terminal-mac stop default # request a normal guest shutdown
  101. ./dist/terminal-mac stop default --force # immediate power-off; unsaved guest work can be lost
  102. ```
  103. Customize a new VM with `--cpus 4 --memory 4 --disk 64 --width 1280 --height 800` (width and height are in points; add `--standard` for a 1x display). CPU, memory and disk arguments are logical CPUs, GiB and GiB respectively. `--offline` omits the guest network device; the shared-folder control channel still works, though some macOS setup workflows may require networking.
  104. ### Networking
  105. By default the guest uses macOS NAT: the host hands out addresses on 192.168.64.0/24 and relays DNS at the gateway. VPN and proxy apps that run in TUN mode (Clash, Surge, sing-box and similar) can leave that relay silent, so the guest keeps an IP but cannot resolve names and looks offline. `--network user` instead bundles [gvproxy](https://github.com/containers/gvisor-tap-vsock) (Apache-2.0, the user-space network stack behind podman machine and vfkit) and runs DHCP, DNS and NAT in user space, with names resolved by the host's own resolver, so the guest stays online wherever the host is:
  106. ```bash
  107. scripts/fetch-gvproxy.sh # once: download gvproxy into vendor/ (checksum pinned)
  108. scripts/build.sh # bundles it into TerminalMac.app
  109. ./dist/terminal-mac create default --ipsw … --network user
  110. ./dist/terminal-mac network default --user # or switch an existing, stopped VM (--nat, --offline)
  111. ```
  112. In user mode the guest is 192.168.127.2 with gateway and DNS at 192.168.127.1; the host answers at 192.168.127.254 (`host.containers.internal`). gvproxy runs as a child of the VM's background process, logs to `runtime.log` and exits with it. `terminal-mac doctor` reports whether gvproxy is bundled; `status` reports the mode in use.
  113. VM data lives in `~/Library/Application Support/terminal-mac/machines/NAME/`. `TERMINAL_MAC_HOME` overrides the data root. Each VM has an exclusive file lock, a sparse disk, hardware identity, auxiliary boot storage, `machine.json`, a private host-control mailbox, the guest exchange directory, and `runtime.log`. A VM boot runs as a separate background process. Lifecycle commands must use the same `TERMINAL_MAC_HOME` as the process that started it.
  114. An interrupted or failed installation leaves its directory and `installed: false` for diagnosis. It is never silently overwritten. To retry, ensure no installer/VM is running, move that incomplete directory aside, then create the VM again. There is deliberately no destructive VM-delete command yet.
  115. ## Isolation model
  116. - Host input and screen APIs are not used for agent actions. The helper refuses to run unless `hw.model` starts with `VirtualMac`. That check prevents accidental host execution; it is not hardware attestation or a defense against a compromised host.
  117. - The guest sees two explicit shares: `control` (read/write, containing request/reply JSON and screenshots) and `tools` (read-only helper app). Host home, project folders, clipboard, microphone, and camera are not attached.
  118. - There is no remote-control network listener. The flat mailbox pins its directory, rejects symlinks, hardlinks and nonregular files on reads, bounds message sizes, checks request IDs, and expires pending actions. The host never executes guest-provided content.
  119. - Default NAT networking permits guest internet access and may reach services on the host or local network. This is **not** a network-isolated or hardened hostile-code environment. `--offline` removes that network path.
  120. - A logged-out/locked guest, missing helper, denied guest permissions, or paused VM prevents normal computer use. TCC grants require interactive guest setup and cannot be bypassed by the CLI.
  121. VM cloning, rollback checkpoints, accessibility snapshots, fully unattended guest setup, terminal splits and tmux transport remain future work. The native Virtualization framework does not itself render a Mac into a terminal or offer an agent input API; this project supplies the guest transport and terminal presentation layers.
  122. ## Development and validation
  123. ```sh
  124. CLANG_MODULE_CACHE_PATH=/tmp/terminal-mac-modules \
  125. SWIFTPM_MODULECACHE_OVERRIDE=/tmp/terminal-mac-modules \
  126. swift test --disable-sandbox --scratch-path /tmp/terminal-mac-build \
  127. --cache-path /tmp/terminal-mac-cache \
  128. --config-path /tmp/terminal-mac-config --security-path /tmp/terminal-mac-security
  129. ```
  130. Tests cover mailbox round trips, expiry and cleanup, file-boundary defenses, name/option validation, fragmented UTF-8 and terminal input sequences. These are automated protocol checks, not evidence that a guest was installed, booted, granted permissions, or controlled successfully. See [docs/VALIDATION.md](docs/VALIDATION.md) for recorded results and the live checklist.
  131. References: [terminal-browser](https://terminal-browser.com/), [Apple's macOS virtualization sample](https://developer.apple.com/documentation/virtualization/running-macos-in-a-virtual-machine-on-apple-silicon), [VZVirtualMachineView](https://developer.apple.com/documentation/virtualization/vzvirtualmachineview), [ScreenCaptureKit](https://developer.apple.com/documentation/screencapturekit).
  132. ## Sponsor
  133. terminal-mac is free and maintained in my own time. [Sponsoring](https://github.com/sponsors/govijr) keeps it that way.
packaging/get.sh · Bundled script · 28 lines · 1 finding marked
  1. #!/bin/bash
  2. # Installs terminal-mac @VERSION@ (build @BUILD@):
  3. # curl -fsSL https://github.com/@REPO@/releases/latest/download/get.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 3 on GitHub
  4. # Options pass through to install.sh, for example: | bash -s -- --prefix "$HOME/.local"
  5. # Downloads one signed archive from GitHub, verifies its SHA-256, then installs it under
  6. # ~/.local without administrator rights. VM data is never touched.
  7. set -euo pipefail
  8. archive='@ARCHIVE@'
  9. url='https://github.com/@REPO@/releases/download/@TAG@/@ARCHIVE@'
  10. sha256='@SHA256@'
  11. [[ "$(uname -s)" = Darwin && "$(uname -m)" = arm64 ]] || { echo 'terminal-mac requires a Mac with Apple silicon.' >&2; exit 1; }
  12. os_major="$(sw_vers -productVersion)"; os_major="${os_major%%.*}"
  13. [[ "$os_major" -ge 14 ]] || { echo 'terminal-mac requires macOS 14 or later.' >&2; exit 1; }
  14. work="$(mktemp -d "${TMPDIR:-/tmp}/terminal-mac-get.XXXXXX")"
  15. trap 'rm -rf "$work"' EXIT
  16. echo "Downloading terminal-mac @VERSION@…"
  17. curl -fL --progress-bar "$url" -o "$work/$archive"
  18. echo "$sha256 $work/$archive" | shasum -a 256 -c - >/dev/null || { echo 'Checksum mismatch; nothing was installed.' >&2; exit 1; }
  19. ditto -x -k "$work/$archive" "$work/unpacked"
  20. bash "$work/unpacked/${archive%.zip}/install.sh" "$@"
  21. cat <<'TEXT'
  22. Next:
  23. terminal-mac # create and open your virtual Mac
  24. claude mcp add terminal-mac -- terminal-mac mcp # computer-use tools for Claude Code
  25. terminal-mac skills install # the agent skill (~/.claude/skills)
  26. terminal-mac mcp --config # config for Cursor, VS Code, Codex…
  27. TEXT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.