「ターミナルの中で macOS が丸ごと動く」——そう聞くと身構えるが、terminal-mac（govijr/terminal-mac・MIT・★1.5k・Swift）の正体は明快だ。Apple Virtualization で建てた“実 macOS のゲスト（VM）”を、ターミナルから表示・操作するツールで、狙いは computer-use AI エージェントに macOS デスクトップを触らせること。agent-desktop がエージェントに“手足”を与えるのと同じ系譜で、こちらは使い捨てにできる別の macOS デスクトップそのものを用意する。この記事は、公式リポジトリ（2026-11-05 確認）をもとに、正体・仕組み・AI 連携・導入・そして隔離の注意までを図解中心に整理する。

まずは動くところを見てほしい。以下は作者によるデモ（X 投稿）だ。

注：terminal-mac の公式リポジトリ自体には画像・デモ動画が無い（上の動画は作者の X 投稿）。本文中の各図は、公式リポジトリの記述から仕組みを図解したものだ。

WHAT IT IS名前で誤解しがち

ターミナルエミュレータではない——実macOSのVM

⚠ こう誤解しがち

✓ 実際はこれ

⚠ こう誤解しがち: macOS標準の Terminal.app のこと？

✓ 実際はこれ: いいえ。ターミナルに表示する別物のツール

⚠ こう誤解しがち: ターミナルエミュレータ（iTerm2 等）？

✓ 実際はこれ: ではない。実macOSのVMをターミナル越しに操作する

⚠ こう誤解しがち: SSHで別のMacに入る？

✓ 実際はこれ: 同一Mac上に Apple Virtualization で建てた仮想macOS

⚠ こう誤解しがち: 人間が使うツール？

✓ 実際はこれ: 主眼は computer-use AIエージェント（人も操作できる）

出典: govijr/terminal-mac README（2026-11-05 確認）。About『Entire MacOS running in your terminal.』

30秒でわかるterminal-mac（2026-11-05）

  • ・Apple Virtualizationで建てた実macOSのVMを、ターミナルから表示・操作するOSS（MIT・★1.5k・Swift）
  • ・狙いはcomputer-use AIエージェント。MCPでClaude Code/Cursor/Codexと連携し screenshot/click/type を仮想Macへ
  • ・物理Macのポインタ・クリップボードは触らない。ホーム/プロジェクト/マイク/カメラは非接続
  • ・ただし既定NATでネット可・堅牢な隔離ではない。early release candidate・自己署名
  • ・要件：Apple silicon・macOS 14+・viewerに Ghostty/Kitty/iTerm2

エージェント基盤の全体像は AIエージェントフレームワーク比較2026｜LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 を起点に。エージェントの“記憶”は claude-mem、スキルの作法は Addy Osmani のエージェントスキル論 でも扱った。terminal-mac は、その“作業場”を仮想 macOS として切り出すピースにあたる。

terminal-mac とは——ターミナルエミュレータではなく「実macOSのVM」

名前が紛らわしいので最初に整理する。terminal-mac は macOS 標準の Terminal.app でも、iTerm2 のようなターミナルエミュレータでもない。実体は、同じ Apple silicon Mac の上に Apple Virtualization で建てた実 macOS のゲスト（VM）で、その画面をターミナルに映し、キーボード・マウス操作を送り込む。SSH で別マシンに入るのとも違い、同一マシン内に隔離した macOS デスクトップをもう一つ持つイメージだ。

なぜそんなものが要るのか。答えは computer-use エージェントにある。AI エージェントに「人間のように画面を見てクリックさせる」とき、あなたが使っている本番のデスクトップを触らせるのは怖い。terminal-mac は、触らせても本体に影響しにくい“別の macOS”を用意し、そこをエージェントの作業場にする。README の一文「A separate macOS desktop for computer-use agents, viewed and controlled from a terminal.」がそのまま設計思想だ。

terminal-mac の仕組み——Apple Virtualization と画面転送

ARCHITECTURE仕組み

実macOSゲスト → 画面差分転送 → ターミナルで描画

  1. Apple Virtualization

    同一 Apple silicon Mac 上に、実 macOS ゲスト（VM）を起動

  2. ゲスト内ヘルパー

    TerminalMacGuest.app が画面をキャプチャし、入力イベントを送る

  3. 画面差分の転送

    変化した画素だけを差分で（最大30fps・lz4圧縮）。viewしていない間は15秒で停止

  4. ターミナルのviewer

    Kitty/iTerm2/Ghostty のグラフィックスプロトコルで描画。Ctrl+]で抜けてもVMは継続

出典: 同 README（2026-11-05 確認）。2x HiDPI 1280×800pt・Swift 6/ScreenCaptureKit/Virtualization

流れはこうだ。まず Apple Virtualization が実 macOS ゲストを起動する。ゲストの中では同梱の TerminalMacGuest.app が動き、画面をキャプチャして、外から来た入力イベント（クリックやキー入力）をゲストに反映する。画面は変化した画素だけを差分で送り（最大 30fps・lz4 圧縮）、ビューアが見ていない間は 15 秒で転送を止めて無駄を省く。ターミナル側の ビューアは、Kitty / iTerm2 / Ghostty のグラフィックスプロトコルを使って、その画面を文字端末の中に描画する。仮想ディスプレイは 2x HiDPI（既定 1280×800pt）だ。

操作面では、タイプ・左右クリック・ダブル/トリプルクリック・ドラッグ・スクロール・矢印や制御キーに対応する。Ctrl+G で Spotlight や Mission Control などの Mac ショートカットのパレットが開き、Ctrl+] でビューアを抜けても VM は動き続ける。つまり「見る」と「動かし続ける」が分離していて、エージェントに任せっぱなしにしてから、必要なときだけ覗く、という使い方ができる。

AIエージェントから操作する——MCPとスキル

terminal-mac の主役はここだ。MCP サーバ（terminal-mac mcp）と skill を提供し、MCP クライアントから仮想 Mac を操作させる。

AGENT CONTROLAIエージェントから操作

MCPクライアント → terminal-mac mcp → 仮想Mac

  1. MCPクライアント

    Claude Code（プラグイン）/ Cursor / VS Code / Codex など

  2. terminal-mac mcp

    MCPサーバ＋skillを提供。claude mcp add terminal-mac -- terminal-mac mcp

  3. 仮想Macを操作

    screenshot / click / drag / scroll / type / key / status を仮想Macへ

  4. 物理Macは不干渉

    同じヘルパー経由。物理Macのポインタやクリップボードは動かさない

出典: 同 README の MCP/skill と操作一覧（2026-11-05 確認）。姉妹プロジェクトに terminal-phone（iOSシミュレータ）

対応クライアントは Claude Code（プラグイン）・Cursor・VS Code・Codex など。エージェントが呼べる操作は screenshot / click / drag / scroll / type / key / status だ。接続はコマンド一つで済む。

# MCP サーバとして登録（Claude Code の例）
claude mcp add terminal-mac -- terminal-mac mcp

# Claude Code のプラグインとして入れる場合
/plugin install terminal-mac --marketplace govijr/terminal-mac

ここで効いてくるのが先の設計だ。エージェントの操作は同梱ヘルパー経由で仮想 Mac に届き、物理 Mac のポインタやクリップボードは動かさない。あなたが別の作業をしている横で、エージェントが仮想 Mac を黙々と操作できる——人間とエージェントの作業が物理的に干渉しない、というのが computer-use 用途での勘所になる。CLI から直接叩くこともできる。

# スクリーンショットを撮る / ビューアを開く（CLI 直接操作の例）
terminal-mac action default screenshot --output /tmp/guest.png
terminal-mac view default

terminal-mac の導入と使い方

SETUP導入の順番

要件 → インストール → 起動 → 接続 → 操作

  1. 1

    要件を満たす

    Apple silicon・macOS 14以降。viewerに Ghostty/Kitty/iTerm2。初回はネット（macOS DL）と最大64GiBの空き

  2. 2

    インストール

    get.sh を取得して実行（SHA-256 検証）。~/.local 以下・管理者権限不要・シェル設定は触らない

  3. 3

    起動

    terminal-mac（ガイド付き）または terminal-mac up

  4. 4

    エージェント接続

    claude mcp add terminal-mac -- terminal-mac mcp、/plugin install でプラグイン導入

  5. 5

    操作・退出

    action … screenshot / view で操作。Ctrl+] で viewer を抜けても VM は動き続ける

出典: 同 README の Install/Usage/Requirements（2026-11-05 確認）。配布版は自己署名・クリーンMacでの受け入れは pending

要件は Apple silicon・macOS 14 以降。インラインのビューアには Ghostty / Kitty / iTerm2 が要る（他のターミナルではネイティブ VM ウィンドウとエージェント CLI になる）。初回は macOS イメージのダウンロードでネットワークが必要で、VM ディスクは既定で最大 64GiB まで伸びる。インストールは次の 1 行だ（README によれば、最新リリースを取得し SHA-256 を検証してから入れる）。

# インストール（~/.local 以下・管理者権限不要・シェル設定は編集しない）
curl -fsSL https://github.com/govijr/terminal-mac/releases/latest/download/get.sh | bash

# 起動（対話端末ではガイド付きフローが始まる）
terminal-mac
# もしくは
terminal-mac up

自分でビルドするなら Xcode 16 / Swift 6 で次のとおり。

bash scripts/build.sh
./dist/terminal-mac doctor

なお curl | bash 形式のインストールは手軽な反面、実行前に中身を読めないのが難点だ。気になるなら、README が案内する ZIP を展開して bash install.sh を使う経路を選び、スクリプトに目を通してから実行するとよい。配布版は現時点で自己署名（notarization なし）なので、Gatekeeper の扱いもあわせて確認したい。

隔離とセキュリティの注意——「堅牢な隔離ではない」

ここは誇張せず、しかしはっきり書く。terminal-mac は「本体に影響しにくい別の macOS」を作るが、それは“堅牢な隔離”とは別物だ。

ISOLATION隔離の範囲と注意

切り離されるものと、隔離は万能でない点

切り離されている

  • ホームディレクトリ
  • プロジェクトフォルダ
  • クリップボード
  • マイク・カメラ

⚠ 注意（README 明記）

  • 既定のNATでゲストはネット接続可
  • ホストやローカルのサービスに到達しうる
  • 『ネットワーク隔離/堅牢な敵対コード環境ではない』
  • early release candidate・自己署名（未notarize）
出典: 同 README のセキュリティ/隔離の記述（2026-11-05 確認）。信頼できないコードの実行環境としては設計されていない

README が明示的に切り離すと述べているのは、ホームディレクトリ・プロジェクトフォルダ・クリップボード・マイク・カメラだ。これらはゲストに接続されない。一方で、同じ README が釘を刺している——「既定の NAT ネットワークによりゲストはインターネットに接続でき、ホストやローカルネットワークのサービスに到達しうる。これはネットワーク隔離された、あるいは堅牢な“敵対的コード”実行環境ではない」。つまり、信頼できないコードやエージェントの暴走を安全に閉じ込める用途には、そのままでは向かない。

実務的には、(1) ネットワークを絞る（到達されたくないホスト/ローカルサービスの前提で設計する）、(2) 認証情報や鍵を仮想 Mac に置かない、(3) early release candidate・自己署名という成熟度を踏まえ、重要資産から離れた環境で試す——あたりが現実的な線だ。「本体のデスクトップを触らせるよりは安全」だが、「何をさせても大丈夫」ではない。この区別を持っておくと事故りにくい。

立ち位置——何に使い、何を選ぶか

terminal-mac が効くのは、エージェントに“GUI の macOS アプリ”を操作させたいときだ。コマンドだけで完結する作業なら、わざわざ VM を建てる必要はない。GUI を伴う検証・反復作業（デスクトップアプリの操作、ブラウザ GUI、macOS 固有の設定画面など）を、本体と干渉せず、使い捨てにできる場所で回したい——そこにはまる。

観点 terminal-mac
与えるもの エージェントに“別の実 macOS デスクトップ”（GUI 丸ごと）
接続 MCP（Claude Code/Cursor/Codex 等）＋ CLI
本体への影響 物理 Mac のポインタ/クリップボード/ホーム等は非干渉
隔離の強さ 基本的な切り離しはあるが堅牢な隔離ではない（既定ネット可）
成熟度 early release candidate・自己署名・Apple silicon 専用

姉妹プロジェクトに terminal-phone（iOS シミュレータ／iPhone 向け）があり、「エージェントにデバイスの GUI を触らせる」という発想のシリーズだと分かる。エージェントの作業場をどう用意するかは、記憶（claude-mem）やスキル（Addy Osmani のエージェントスキル論）と並ぶ、computer-use 時代の設計ピースだ。まず試すなら、重要データのない環境で terminal-mac up →スクリーンショットを撮らせてみて、ネットワークの既定（NAT）だけは最初に意識しておきたい。

参照ソース