iOS端末 × Tailscale × Moshi × tmux で Antigravity CLI 遠隔開発環境を構築したノウハウ記事
iPhoneからMacを遠隔操作して`Antigravity`でAI開発する環境を作ろうとしたら沼にハマった話(全部再起動で何とかなった)
※このポストはAIによって生成されています。
iPhoneなどのモバイル端末から、自宅のMacにSSH接続してAntigravity CLI（agy）を動かし、どこでもAI主導で開発できる環境を構築しようと試みました。
基本的には快適な開発環境が作れたのですが、途中で 「ls を打つとターミナルが完全にフリーズする」「tmux 内で agy のOAuth認証がどうしても通らない」「端末のスクロールが効かなくなる」 という沼にハマってしまいました。
今回は、スマホ＋SSH＋tmux という環境で快適なCLI開発環境を構築する手順と、その中で直面したトラブルの回避ノウハウをまとめます。
構築したかった「どこでも開発できる」環境
今回の構成のゴールは以下のようなイメージです。
- iOS端末（Moshiアプリなど） から Tailscale 経由で自宅のMacに安全にSSH接続
- Mac上では
tmuxを常時起動し、接続が切れても開発作業のコンテキストを保持 - CLIツールである Antigravity（
agy） を使って、iPhoneからAIに指示を出してコードを生成・改修
自分だけのプライベートな環境なので、外部にポートを開放せず、安全かつライトに開発できるのが魅力です。
しかし、実際に運用してみると Mac特有の仕様 や tmux 内部の環境変数の壁 に相次いで衝突しました。
ハマったポイントと回避Tips集
実際に遭遇したエラーやトラブルと、その解決策をまとめます。
ls を打つとターミナルが返ってこなくなる問題
現象
~/Documents 配下のディレクトリに移動して ls を実行した瞬間、コマンドの返答がなくなり、Ctrl + C も効かないフリーズ状態になりました。一方で、ホーム直下（~）などでは普通に ls が動くという現象が発生しました。
原因
~/Documents（書類）や ~/Desktop（デスクトップ）は、macOSの iCloud Drive 自動同期 や TCC（プライバシー保護機能） の監視対象になっています。
tmux のサーバープロセスがバックグラウンドで動く際、これらの権限チェックや iCloud のメタデータ読み込みと干渉し、カーネルレベルでファイルシステムのデッドロック（応答なし）が発生していたことが原因でした。
最悪の場合、iCloud の同期プロセス（bird）すら killall bird で殺せなくなります。
解決策
- まずは Mac を再起動する カーネルレベルでデッドロックしている場合、コマンドでの復旧は不可能です。素直に Mac を再起動してカーネルロックを解放するのが安全です。
- 再起動後にそのまま作業を再開する
再起動を行えばプロセスとカーネルロックが一度完全にリセットされるため、
~/Documents配下でも正常にlsや操作が行えるようになります。
tmux 内で画面スクロールができず長いURLが確認できない問題
現象
agy のログイン時に表示される長い認証URLが画面上部にはみ出してしまい、スマホのタップ操作やドラッグを行っても画面を上にスクロールできず、URL全体を確認・コピーできない状態になりました。
原因
tmux 内では標準の端末スクロール機能が一時的に無効化され、独自の画面管理モードになっているためです。マウス・タッチ操作のスクロールが通らない設定になっていると、画面外に流れたログを追うことができません。
解決策：tmux のコピーモードを使う
tmux 標準のコピーモード（スクロールモード）に入ることで解決します。
Ctrl + bを押した後に[を押す（コピーモード開始）- 矢印キー（または
PageUp/kキーなど）で上にスクロールし、流れてしまったURLやテキストを確認・選択する - 終了したいときは
qキーを押す
※ 設定ファイル（~/.tmux.conf）に set -g mouse on を書いておくと、スマホのタップドラッグでもスクロール可能になります。
tmux 内で agy（Antigravity）の OAuth 認証が通らない問題
現象
tmux 上で agy を起動して Google アカウントの OAuth 認証（URL発行 ➔ ブラウザで認証 ➔ コード貼り付け）を行おうとすると、以下のようなエラーが出続けてログインできませんでした。
Got an error: token exchange failed: oauth2: "invalid_grant" "Invalid code verifier."
原因
tmux 内の仮想端末（TTY）や、スマホのキーボードから送信される改行コード（\r\n）の兼ね合いで、貼り付けたコードの末尾に不可視の制御文字が混入してしまうことが原因です。また、tmux 起動時に親プロセスの環境変数が正しく引き継がれず、ローカルのトークン情報（~/.antigravity）を参照できていないケースもありました。
解決策：認証は「素のターミナル」で行い、環境変数を引き継ぐ設定を入れる
tmux やスマホの画面上で無理に OAuth 認証のやり取りをする必要はありません。
tmuxの外（Mac本体の素のターミナル）でagyを起動してログインする
agy login
Mac 本体のブラウザで認証を完了させると、ホーム直下にトークン情報が正しく保存されます。
- 認証後に
tmuxに入る
tmux attach -t dev
すでにトークンが存在するため、tmux 内で agy を打っても認証プロンプトを出さずに直接ログイン済み状態で起動してくれます。
「認証作業だけは Mac 本体の素のターミナルで行い、普段の作業だけを tmux やスマホから行う」 と切り分けるのが確実です。
最終的な ~/.tmux.conf の設定例
スクロールの有効化や、tmux 内で環境変数（HOME や PATH 等）がズレて認証エラーやコマンド不整合が再発するのを防ぐため、~/.tmux.conf に以下の設定を入れておくことをおすすめします。
# ~/.tmux.conf
# マウス・タッチスクロールを有効化
set -g mouse on
# 親プロセス（素のターミナル）の環境変数を完全に引き継ぐ
set -g update-environment "PATH HOME USER SHELL TERM XDG_CONFIG_HOME TMPDIR"
# 256色カラー対応
set -g default-terminal "screen-256color"
設定の反映コマンド
設定ファイルを編集した後は、以下のコマンドで反映させます。
tmux source ~/.tmux.conf
※ 環境変数の変更を確実に適用させたい場合は、一度 tmux kill-server でサーバーを落としてから再起動するのが確実です。
tmux で「no server running」と出たときの復旧
Mac を再起動した直後などに tmux source ~/.tmux.conf や tmux ls を打つと、以下のエラーが出ます。
no server running on /private/tmp/tmux-501/default
これはエラーではなく、「Mac 再起動によって tmux サーバープロセスが終了したため、現在起動しているセッションがない」という状態を示しています。
以下のコマンドで新しいセッションを作れば、自動的に tmux サーバーが立ち上がり、設定ファイルも読み込まれます。
# dev という名前で新規セッションを作成してアタッチ
tmux new -s dev
# セッションがあれば入り、なければ新規作成するコマンド
tmux new-session -A -s dev
最後に
iPhone ＋ SSH ＋ tmux ＋ Antigravity という構成が一度組み上がってしまえば、出先やベッドの上からでもサクッと Mac のパワーを使って AI 主導の開発を進められるようになります。
macOS 特有の仕様や tmux の環境変数・操作感の癖など、CLI 開発ならではのハマりポイントはいくつかありますが、一度対処してしまえばスムーズに運用可能です。
同じようにスマホからのリモート CLI 開発環境を作ろうとして固まってしまった方の参考になれば幸いです！
