macOS のアプリを書いていると、あるで手が止まります。ビルドした debug build をして、「ちゃんとが出るか」をたい。バーでも、でも、でも。やることはなはずなのに、の機でこれをやると、なぜか甲板がます。

気になったので、なぜのかを一つずつでてみました。が見えてくると、道も見えてきます。

解決したい問題

は lyra という macOS アプリ（再生中のとをデスクトップに重ねる）を書いていて、このでいくつもました。機をして、debug build をて、を。それだけのことが、なかなかに進みません。

してみると、さのは三つに分かれていました。一つは launchd に飼われたが、てもこと。二つはと debug がをこと。三つは debug build がのとを食うこと。

同じごとにている人がいるかもしれないので、でやってみたことを置いておきます。機を一切ずに OS のをする、そのの話です。

この記事を読み終えたら手に入るもの

• 機をずに macOS アプリを OS でる
• なぜ「のマシンでの」がだらけなのか、その
• UTM の Apple バックエンドで utmctl exec が使えないというと、その
• boot / run / capture / restore といったの方と、そのにある
• GUI にを挿す launchctl asuser の方と、それがとが出ない

前提

• ホスト: macOS、Apple Silicon。UTM を入れてあること（brew install --cask utm）
• ゲスト: UTM 上に macOS 15+ の VM を Apple 仮想化バックエンドで済み。Remote Login (SSH) をにし、admin をてある前提
• : ssh / scp と bash がること
• スコープ外: VM のそのもの（SSH の込み、passwordless sudo のなど）はここではしません。はで組んだのです

なぜ開発機での確認が厄介なのか

三つの罠を、一つずつ並べて潰す

は三つ。でる前に、一個ずつてみます。

罠その一: launchd KeepAlive の蘇生

Homebrew でとして入れたアプリは、launchd に homebrew.mxcl.lyra としてされます。なのは、こいつの KeepAlive が true だということ。

つまり SIGTERM だろうが SIGKILL だろうが、たに launchd がにします。lyra stop（は kill）をても、また出てきます。には、KeepAlive のそのものをするしかありません。

brew services stop lyra
# 中身はこれ:
# launchctl bootout gui/$UID/homebrew.mxcl.lyra

launchctl bootout で GUI から出して、ようやくになります。はこれをずに kill をしていて、しばらくないを過ごしました。

罠その二: single-instance flock の奪い合い

lyra は ~/.cache/lyra/lyra.pid に flock を掛けて、に二がないようにしています。のいいです。とはいえ時にはをます。

がていると、debug build はをずにします。にをやりできたとしても、今度はがにれて、どちらをいるのか分からなくなります。のか、たった今したか。のつかないは、になりません。

罠その三: 本番の設定とキャッシュを食う

debug build も ~/.config/lyra/ ののと ~/.cache/lyra/ をます。をして、にをます。

のつもりでをいじって、を。あるいは debug build がたたキャッシュがて、次にがしたときにそのを。が場とをている、このはられません。

並べてみてたのは、この三つはのに見えて、一点にを持つ、ということでした。するとするがだから。なら、を物理的にればいい。機はだけして、はクリーンなマシンへ。とはいえ、もう一台 Mac を買うのはです。だから VM を使ってみました。

なぜ UTM の VM なのか

UTM は macOS の上で VM を回すです。Apple Silicon なら Apple 仮想化バックエンド（AVF）が使えて、これはて。ゲストがたらスナップショットをだけ。機はのまま。ちょうどよさそうだったので、まずでてみました。

ところが、にていないを一つました。

Apple バックエンドでは utmctl の ip-address も exec もません。 これらは QEMU バックエンドのです。AVF ゲストに utmctl exec をても、もてきません。

ていたのとました。ではありません。とのがずれていた、ただそれだけのことです。じゃあどうやってゲストをか。はで、全部 SSH でやる です。ゲストにの SSH （~/.ssh/vm_rsa）をで、のも、のも、スクリーンショットのも、ぜんぶ ssh と scp でます。utmctl には、こいつにしかできない start / stop / status だけ。

手順 — ハーネスの設計判断

ここからがです。lyra-vm-harness.sh という一本のスクリプトにました。サブコマンドで、ごとにを分けています。

lyra-vm-harness.sh boot     <vm>          # utmctl start + SSH ポーリング (120s timeout)
lyra-vm-harness.sh run      <vm>          # swift build → scp → /tmp install → daemon 起動
lyra-vm-harness.sh exec     <vm> -- <cmd> # SSH でコマンド実行
lyra-vm-harness.sh capture  <vm> [dir]    # スクリーンショット + unified log + process sample
lyra-vm-harness.sh restore  <vm>          # daemon 停止 + brew service 状態を復元
lyra-vm-harness.sh shutdown <vm>          # graceful shutdown

ででいくうちに、四つのがました。「なんでそうなっているのか」がないとしづらいなので、一つずつにしていきます。

1. utmctl exec ではなく SSH を土台にする

になるはこれだけです。SSH のを一個のにで、あとはこいつをます。

ssh_run() {
    local ip="$1"; shift
    ssh -i "$LYRA_VM_SSH_KEY" -p "$LYRA_VM_SSH_PORT" \
        -o StrictHostKeyChecking=no -o BatchMode=yes -o ConnectTimeout=10 \
        "${LYRA_VM_SSH_USER}@${ip}" "$@"
}

なぜ utmctl exec をないか。は二つです。

一つはの、AVF バックエンドでそもそもない。これは的です。もう一つ。にたとしても、utmctl exec は GUI をします。Homebrew も launchd も AppKit も、（PATH や TMPDIR）がていないとません。SSH でとして入れば、そのがからています。GUI アプリをたいなら、GUI のごとのがでした。

2. launchctl asuser で GUI にデーモンを挿す

窓を出すには、GUI セッションの中に挿し込む必要がある

これが一番たです。

SSH で入って、ゲストの中で nohup lyra daemon & とやってみました。PID はてきます。もています。なのに——が一枚も出ません。 なに、ているはずのだけがています。

は、SSH には window server へのがからでした。AppKit の NSWindow は、の GUI のでないとにを出せません。SSH でしたは、どの GUI にもないのでした。

はこれです。launchctl asuser で、の GUI bootstrap namespace にをます。まず /tmp/lyra-vm-launch.sh というスクリプトをゲストにます。

# /tmp/lyra-vm-launch.sh の内容 (ゲスト側に生成して渡す)
#!/bin/sh
export UV_CACHE_DIR=/tmp/lyra-vm-uv-cache
nohup /tmp/lyra-vm-test/lyra daemon > /tmp/lyra-vm-daemon.log 2>&1 &
echo "$!" > /tmp/lyra-vm-daemon.pid

UV_CACHE_DIR を /tmp にのは、sudo でした root がの ~/.cache に root のをないためです。と PID をの /tmp にのにもがあって、sudo は $HOME を /var/root にので、$HOME を使うと SSH からないになります。

次に id -u での UID をて、sudo launchctl asuser <uid> でそのの GUI namespace のでします。

local uid
uid=$(ssh_run "$ip" "id -u")
ssh_run "$ip" "sudo launchctl asuser $uid /tmp/lyra-vm-launch.sh"

これでて NSWindow が window server にて、にが出ました。UID をせず id -u でているのは、ゲストのがてもないようにです。がてもにしておきます。

3. /tmp への隔離インストール

ゲストにも brew でたの lyra がいます。これを debug build で**にしない。** したら、ゲストの clean state がて、restore のがます。だから debug build は /tmp のディレクトリに install します。

# ホストでビルドしてゲストの /tmp/lyra-drop に転送
swift build -c release
scp -i "$LYRA_VM_SSH_KEY" .build/release/lyra "${LYRA_VM_SSH_USER}@${ip}:/tmp/lyra-drop/"
# Bundle.module lookup に必要な *.bundle も転送
for bundle in .build/release/*.bundle; do
    [ -d "$bundle" ] && scp -r -i "$LYRA_VM_SSH_KEY" "$bundle" "${LYRA_VM_SSH_USER}@${ip}:/tmp/lyra-drop/"
done

# /tmp の隔離ディレクトリにインストール（brew 管理バイナリは絶対に触らない）
ssh_run "$ip" "rm -rf /tmp/lyra-vm-test && mkdir -p /tmp/lyra-vm-test"
ssh_run "$ip" "install -m 755 /tmp/lyra-drop/lyra /tmp/lyra-vm-test/lyra"

/tmp にば、ゲストをするか restore すればもなくます。brew がしているには一本ていません。がのでします。

4. kill -0 による起動直後の生死確認

nohup ... & ですると、PID はにてきます。とはいえ、したにこともあります。ミス、の、なんでも。PID はあるのに、はもうでいる。

ここでの「」をしたら、に向かってスクリーンショットをことになります。だから 3 て、だけます。

sleep 3
if ! ssh_run "$ip" "kill -0 '$pid' 2>/dev/null"; then
    ssh_run "$ip" "tail -n 40 /tmp/lyra-vm-test/lyra.log" >&2
    echo "daemon は起動直後に沈んだ" >&2
    exit 1
fi

kill -0 はにてシグナルをません。がするかどうかだけをます。ていれば、でいれば。3 のをてからことで、「はしたがた」をます。だなら、てクラッシュをせてます。はなほうがいいので。

検証 — スクリーンショットを回収する

がていることをたら、をます。capture のです。ここでも一つをました。うとしたにゲストのディスプレイがしていると、のはなだけでした。

だからに caffeinate -u -t 3 でディスプレイをて、UTM の ID を CGWindowListCopyWindowInfo でて、screencapture -l <wid> でそのだけます。これはホストのです。

# ホスト側で UTM ウィンドウの window id を取得
utm_wid="$(swift - <<'SWIFT'
import CoreGraphics
let wins = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String:Any]]
let candidates = wins.compactMap { w -> (Int, Int)? in
    guard let owner = w["kCGWindowOwnerName"] as? String, owner == "UTM",
          let num = w["kCGWindowNumber"] as? Int,
          let bounds = w["kCGWindowBounds"] as? [String:Any],
          let w2 = bounds["Width"] as? CGFloat, let h2 = bounds["Height"] as? CGFloat
    else { return nil }
    return (num, Int(w2 * h2))
}.sorted { $0.1 > $1.1 }
if let best = candidates.first { print(best.0) }
SWIFT
)"

# 撮影直前にディスプレイを起こして、UTM ウィンドウだけキャプチャ
caffeinate -u -t 3 &
screencapture -l "$utm_wid" "$out_dir/screenshot.png"

caffeinate -u -t 3 で 3 だけをてディスプレイをます。Swift のは UTM を「」でます——VM のがいちばんからです。capture はだけでなく、log show の unified log と sample による process sample もにします。は「が出たか」だけでなく、「どうているか」までてこそ、とでてみてました。

落とし穴

後始末を trap に縛りつけて、必ず clean state へ戻す

症状: utmctl exec が無言で何も返さない

: Apple バックエンドでは utmctl exec / ip-address が。QEMU です。 : のを SSH にます。IP はでするか、Bridged networking で DHCP にするとでした。

症状: デーモンは生きているのに窓が一枚も出ない

: SSH には window server が。NSWindow は GUI のでないとできません。 : sudo launchctl asuser $(id -u) <起動スクリプト> で、の GUI namespace にます。

症状: スクリーンショットが真っ黒

: キャプチャのにゲストのディスプレイがしていた。 : caffeinate -u -t 3 & でにディスプレイをます。

症状: 確認の途中で落ちて、状態が散らかったまま残る

ゲストをないのがなら、もくらいです。一番のは、のでスクリプトがて、がしっぱなし・brew がたままされることでした。次ので「あれ、がおかしい」が始まります。

だから trap で restore を EXIT につけます。

# 確認の典型的な航海:
.claude/scripts/lyra-vm-harness.sh boot "lyra-test-vm"
trap ".claude/scripts/lyra-vm-harness.sh restore 'lyra-test-vm'" EXIT
.claude/scripts/lyra-vm-harness.sh run "lyra-test-vm"
.claude/scripts/lyra-vm-harness.sh capture "lyra-test-vm" ./artifacts
.claude/scripts/lyra-vm-harness.sh shutdown "lyra-test-vm"

restore は二つやります。/tmp の debug をて、ゲストの brew をのにます。これを EXIT trap にておけば、スクリプトがにろうが、でうが、Ctrl-C でれようが、ゲストは clean state にます。すると、boot のでは utmctl start のに SSH がまでします。macOS ゲストは SSH がまで 60〜90 かかることがあるので、タイムアウトは 120 おくとでした。くと、まだていないゲストに「でいる」とをことになります。

次の一手

ここまでで、機を一切ずに macOS アプリを OS ではました。のアプリでやってみるなら、まずの「源」を三つてみてもいいかもしれません。launchd のはか、single-instance はどこか、とキャッシュはどのをか。それがば、run と restore のをのアプリにだけです。

てみてたのは、さのはたよりだった、という一点でした。そうに見えていたのは、とがでていた、ただそれだけ。をのにたら、三つのはにました。とはいえ、この VM ハーネスはが出るところまでで、クリックやキーといった UI のまではていません。そこまでなら、またのです。

図はておきました。あとはので、にてみてください。