OpenHandsのMac自主管理は、個人の低頻度利用ならローカルMac、複数人の並列実行や継続稼働ならクラウドMacを選ぶのが基本です。Appleプロジェクトを扱う場合は、Agentの実行場所だけでなく、Xcodeビルドと署名まで同じmacOS環境で検証できるかを先に確認してください。

症状： インストールは成功したのに、実際のリポジトリでテスト、シミュレーター、署名まで完了できない。
最短の解決策： まず本物のリポジトリを短期間動かし、占有時間、並列数、認証情報の分離、Xcodeの受け入れ結果を確認してから長期構成を決めます。

この内容は、低コストでOpenHandsを試したい個人開発者、複数人に統一されたAgent環境を提供したいプラットフォーム担当者、iOS・macOS案件の検証環境を整えたい技術責任者向けです。

最初に確認すべき失敗パターン

典型的な失敗は、Dockerイメージの取得とWeb画面の起動までは成功したものの、実際のAppleプロジェクトの受け入れ段階で止まるケースです。Swiftファイルの編集、一般的なテスト、Git操作は進んでも、Xcodeのビルド設定、シミュレーター、署名証明書、キーチェーンに依存する工程が別の環境へ分断されるためです。

公式の導入手順では、CLIを使う方法に加えてDockerから起動する方法が示されています。Docker構成では通常、Web画面の公開、OpenHandsの状態保存、ワークスペースのマウント、Agent実行用のDocker接続を個別に扱います。つまり、起動コマンドが短くても、実際の運用では保存先と公開範囲が停止原因や情報漏えい範囲を左右します。(OpenHands公式のローカル構築手順)

ローカルMacが開発作業を止める場面

自分のMacへOpenHandsを構築する最大の利点は、手元のリポジトリと設定をすぐ渡せることです。低頻度の試用、短いバグ修正、作業中に画面を確認する用途なら、別の環境を契約せずに始められます。

ただし、次の3つが重なると、開発機をAgent専用に近い状態へ追い込むことがあります。

  • 長時間の依存関係インストールやテストで、通常のIDE作業とCPU、ディスクI/O、Docker処理が競合する。
  • Agentが停止したとき、作業中のMacと実行環境が同時に使えなくなる。
  • 外出先やチームメンバーからアクセスするには、電源、スリープ、VPN、ポート公開、認証を別途管理する必要がある。

公式のDocker起動例では、Web画面をホストのポート3000へ公開し、~/.openhandsとワークスペースをコンテナへマウントしています。つまり、起動コマンドが短くても、実際の運用では保存先と公開範囲が停止原因や情報漏えい範囲を左右します。(OpenHands公式のDocker起動例)

経験上の判断： 自分だけが、作業時間中に、1つのリポジトリを短く処理するならローカルMacで十分です。夜間実行、常時接続、複数リポジトリの同時処理を始める時点で、開発用Macから実行用Macを分ける価値が高まります。

Docker Runtimeの隔離範囲

Docker Runtimeは、Agentがシェルやファイル操作を行う場所をコンテナへ分けるための仕組みです。しかし、コンテナを使ったからといって、ホストMacから完全に切り離された安全境界になるわけではありません。

確認すべき範囲は4つあります。

  1. ワークスペースのマウント
    バインドマウントは標準では読み書き可能です。Agentが必要とするディレクトリだけを渡し、可能なら読み取り専用を使い、秘密鍵や個人設定を同じ階層へ置かない構成にします。(Docker公式のバインドマウント説明)

  2. Dockerソケット
    OpenHandsの公式Docker構成には、実行用コンテナを作るためのDockerソケットマウントが含まれます。Dockerソケットへ到達できる設計は、単なるソースコード編集より強い権限を持つため、専用ホストや許可イメージ、監査ログを検討すべきです。(OpenHandsの公式Docker Compose設定)

  3. ネットワークアクセス
    Agentがパッケージレジストリ、Gitホスト、外部APIへ接続できるなら、依存関係の取得は便利になります。一方で、不要な外向き通信を許すと、誤ったスクリプトや漏えいしたトークンの影響が広がります。

  4. ホスト側の認証情報
    Git設定、クラウド鍵、Apple関連の証明書を安易にマウントしないでください。ローカルMacでは失敗の影響が個人の開発環境全体へ及びやすく、独立したクラウドMacなら用途ごとにアカウントと保存領域を分けやすくなります。

複数Agentの衝突と待ち行列

OpenHandsで複数のAgentを動かす場合、問題は単純な処理速度だけではありません。同じワークスペースでブランチを切り替える、同じ開発用ポートを使う、同じ依存関係キャッシュを書き換えるといった競合が発生します。

判断は次のように分けると現実的です。

  • 独立開発者：1つのリポジトリを手動で確認するなら、既存Mac上の単一実行環境で開始します。
  • 共有する小規模チーム：人ごとにワークスペースと認証情報を分け、専用のローカルMacまたは専用クラウドMacを使います。
  • 自動化プラットフォーム：タスクごとに実行環境を分離し、ログ、キュー、停止、再試行を管理できるクラウド構成を選びます。

ここで重要なのは、Agentの数を先に決めないことです。まず2つの異なるリポジトリを同時に実行し、ポート、依存関係、ログ、作業ブランチが互いに影響しないか確認してください。衝突が起きた時に手動で直す運用なら、人数が増えた時点で待ち時間がそのまま保守負担になります。

Appleツールチェーンの受け入れ条件

Swiftのソースコードを変更するだけなら、Linux系のコンテナや一般的なDocker環境でも作業できる場合があります。しかし、Xcodeでのビルド、シミュレーター起動、アーカイブ、コード署名は別の確認項目です。

Appleの資料では、Xcodeにxcodebuild、xcrun、notarytoolなどの開発用コマンドが含まれると説明されています。また、Command Line Toolsだけではxcodebuildとxctraceを利用できません。(Apple公式のCommand Line Tools説明)

署名や配布工程では、Xcodeまたはxcodebuildでアーカイブを作成し、署名済みアプリをエクスポートします。macOSアプリではDeveloper IDや公証も関係するため、コンテナ内でコードを書けたことを、Apple向けの受け入れ完了と同じ意味で扱わないでください。(Apple公式のMac向け署名済みコード作成手順)

この段階で、次の順番で検証します。

  1. Xcodeのバージョンと対象SDKを確認します。
  2. xcodebuild -versionとxcode-select -pで選択中の開発環境を確認します。
  3. Agentにソース修正だけを依頼し、変更差分を保存します。
  4. 同じmacOS環境で通常のビルドとテストを実行します。
  5. シミュレーターを使うUIテストを実行します。
  6. 署名、アーカイブ、必要なら公証まで行い、失敗ログをAgentへ戻します。

再構築を減らす実行手順

OpenHandsでは、実行用イメージのタグやカスタムイメージを固定することで、毎回異なる環境を引く問題を抑えられます。公式のDocker例でも、Agent Serverのイメージリポジトリとタグを環境変数で指定しています。バージョンを固定し、プロジェクト固有の依存関係をカスタムイメージへ寄せるのが基本です。(OpenHands公式のRuntime設定説明)

運用時は次の6段階で進めてください。

  1. 対象リポジトリを専用ディレクトリへ複製します。
  2. OpenHands本体、Agent Server、Runtimeのタグを記録します。
  3. ワークスペース、状態保存先、ログ保存先を分けます。
  4. Dockerソケット、バインドマウント、外向き通信を必要最小限にします。
  5. 2つの異なるタスクを同時に実行し、競合と復旧を確認します。
  6. Xcodeビルドと署名を含む実リポジトリで受け入れ試験を行います。

ローカルMacは一度取得したイメージや依存関係を再利用しやすい一方、設定が個人の環境に蓄積します。クラウドMacは標準イメージを再配布しやすく、担当者が変わっても同じ構成へ戻しやすい点が優れています。

運用方式を決めるチェックリスト

次の項目にチェックを入れ、左側が多ければローカルMac、右側が多ければクラウドMacを選んでください。両方にチェックが付く場合は、一般的なAgent処理とAppleの受け入れ工程を分ける混合構成が候補です。

ローカルMacを選ぶ項目

  • [ ] 利用者は自分一人で、低頻度の手動実行が中心です。
  • [ ] OpenHandsの実行中に、自分のMacが一時的に占有されても問題ありません。
  • [ ] 外部から常時アクセスする必要がありません。
  • [ ] Appleツールチェーンの確認を自分のMacで行えます。
  • [ ] Dockerソケット、ワークスペース、認証情報の管理を自分で引き受けられます。

判定： 5項目のうち4項目以上に該当し、夜間処理や複数人の共有がないなら、既存のMacで試す価値があります。該当項目が3項目以下なら、開発作業とAgent実行を分離する構成を優先してください。

クラウドMacを選ぶ項目

  • [ ] 複数人が同じAgent環境へ接続します。
  • [ ] 夜間、CI、スケジュール処理など継続稼働が必要です。
  • [ ] 開発機とAgentの障害範囲を分けたいです。
  • [ ] リポジトリ、ログ、資格情報を利用者ごとに隔離したいです。
  • [ ] 外出先から接続し、再起動や交換を自分のMacなしで行いたいです。

判定： 5項目のうち2項目以上に該当し、さらにAppleプロジェクトを継続的に検証するなら、独立したクラウドMacを短期試用してください。並列処理が増える場合は、1台へ無理に集約せず、ワークスペースと実行単位を分けられるかを確認します。

混合構成を選ぶ項目

  • [ ] 一般的なコード修正やレビューと、Xcode検証の実行頻度が異なります。
  • [ ] バックエンド案件とApple案件で、必要な依存関係が大きく異なります。
  • [ ] 開発者のMacへ署名証明書や本番用資格情報を置きたくありません。
  • [ ] Agentの処理は遠隔で継続させつつ、最終確認だけMacで行いたいです。

判定： 2項目以上に該当するなら、汎用タスクを分離された実行環境へ置き、Xcode、シミュレーター、署名だけをmacOS環境へ渡す設計が適しています。Apple案件と一般的なバックエンド案件を同じホストへ押し込まず、受け入れ工程だけをMacへ集約すると、コストと隔離のバランスを取りやすくなります。

注意： クラウドへ移すだけで安全になるわけではありません。専用環境でも、公開ポート、管理者権限、Dockerソケット、GitやAppleの資格情報を誤って共有すれば、影響範囲は広がります。

短期の構成確認では、Macのレンタルプランを比較し、実際のリポジトリで起動、並列実行、Xcode検証まで確認してください。地域や接続経路が作業に影響する場合は、自動化環境のチェック項目も合わせて確認すると、導入後の見落としを減らせます。

FAQ

OpenHandsはMacにそのまま構築できますか？

できます。公式ドキュメントにはmacOS上でのCLI導入とDocker利用の手順があります。ただし、Docker Runtimeを使う構成ではDocker Desktop、ワークスペースのマウント、Dockerソケットの扱いを確認する必要があります。iOSやmacOSアプリの最終検証まで行う場合は、コンテナ内だけで完結させず、Xcodeが利用できるmacOS環境で受け入れ試験を実施してください。

ローカル構築とクラウド構築はどう選びますか？

一人で短時間だけ試すなら、既存のMacに構築する方法が合理的です。一方、常時アクセス、複数人の利用、認証情報を分けた運用、作業中のMacを占有されたくない場合は、独立したクラウドMacのほうが管理しやすくなります。初期導入の速さより、停止時の影響範囲と復旧手順を優先してください。

複数のAgentを動かすには何が必要ですか？

複数のAgentを動かすには、プロジェクトごとのワークスペース、ポート、依存関係、キャッシュ、ログを分離できる構成が必要です。単一の開発Macで無理に共有すると、同じディレクトリや開発用サービスを奪い合う可能性があります。小規模なら専用Mac、大規模または継続運用なら複数の実行環境を持つクラウド構成が適しています。

iOSやmacOSのプロジェクトを扱えますか？

Swiftの編集や静的なコード変更だけなら、一般的な実行環境でも進められます。しかし、Xcodeビルド、シミュレーター試験、署名、アーカイブ、提出前の確認にはmacOS上のAppleツールチェーンが必要です。Docker RuntimeだけでApple向けの受け入れ試験まで完了できるとは判断せず、実際のXcode環境で検証してください。

最終判断

現在のローカルMac運用は、低頻度の試用には安価で始めやすい反面、開発作業とのリソース競合、Macのスリープや停止による中断、個人の資格情報とDocker権限が同じホストへ集まる問題があります。共有サーバーとして使い続ける場合は、利用者ごとのワークスペース分離や復旧手順も必要です。

そのため、まず短い期間で実際のリポジトリを動かし、Agentの変更、テスト、Xcodeの受け入れまで確認してください。結果として一人の手動利用に収まるならローカルMacを継続し、並列実行や常時接続が必要ならSSHMacのクラウドMacへ分離するほうが、開発機を止めずに運用しやすくなります。長期契約を先に決めるのではなく、OpenHandsの処理とAppleツールチェーンの境界を短期試用で確かめてから、固定環境へ移行するのが安全です。