OpenHands Agent Canvasのインストール方法は？2026年デスクトップ版、Docker、それともリモートバックエンド

症状：初回起動を急ぎたいのに、Node.js、権限、接続先の違いで迷っている。
最短解決：個人の試用はデスクトッププレビュー版またはnpx、ファイル境界が必要ならDocker、常時稼働やチーム共有ならリモートバックエンドを選びます。

この判断は、OpenHands Agent Canvasのインストール方法を「画面の起動方法」だけでなく、Agentがどこで動き、何にアクセスでき、停止したとき何が残るかで決めるものです。デスクトップ版は導入手順を減らしますが、サンドボックスやサーバー級の分離を提供するものではありません。

個人で初回試用をしたい人、Node.jsやuvの準備に不慣れな人、ローカルプロジェクトへのアクセス範囲を制限したいDocker利用者、そしてチーム用に継続稼働するバックエンドを用意するプラットフォーム担当者が対象です。

最終更新：2026年9月6日。対応方式、プレビュー状態、接続方法は、Agent Canvas公式セットアップ資料、アーキテクチャ説明、1.16.0の公式リリースノートを基に確認しています。

先に選択肢を絞る：5つの利用場面

ここでいうCanvasは操作画面であり、実際にAgentがツールを実行するバックエンドや、コードを保持する実行環境とは別の構成要素です。公式のAgent Canvasアーキテクチャ資料でも、この分離を前提に接続先を考える必要があります。

方式ごとの違いは「インストール量」より実行権限にある

デスクトッププレビュー版

Agent Canvas Desktop Appは、画面を開くまでの準備を減らしやすい方式です。初回試用では、依存関係の確認やターミナル操作に時間を使わず、Canvasを開いてバックエンドへ接続し、短いタスクを投入できます。

ただし、デスクトップ版が動いているからといって、Agentの操作対象が自動的に隔離されるわけではありません。ローカルのバックエンドをユーザー権限で起動しているなら、Agentの読み書き可能範囲は、そのプロセスと作業ディレクトリの権限設計に左右されます。公式にはmacOS、Windows、Linux向けアプリはいずれも早期プレビューとして扱われているため、チームの標準環境にする前に更新経路と対応状況を確認してください。

npx・npm

npxやnpmを使う構成は、起動手順を記録しやすく、短時間の検証や開発者ごとの試行に向いています。一方で、Node.jsの導入、バージョン管理、依存パッケージの更新、ターミナル終了後のプロセス維持を自分で扱う必要があります。Node.js公式のパッケージマネージャー案内に沿って、使用する環境の導入方法を固定してください。

ターミナルを閉じるとCanvasだけでなく、同じ端末上のバックエンドも停止する構成では、長時間タスクの継続性を期待できません。短いタスクの確認には十分でも、作業中に端末を移動させる用途では後述のリモート方式へ切り替えるべきです。

Docker

Dockerでは、Agentが動く環境と、Canvasを表示する環境を分けやすくなります。プロジェクトを特定のディレクトリだけマウントし、設定や作業結果をボリュームへ保存すれば、起動手順とファイル境界を再現しやすくなります。Dockerのボリューム保存仕様では、コンテナのライフサイクルとデータの保存先を分けて考えられます。

ただし、コンテナは完全なテナント分離ではありません。ホストのソケット、広すぎるマウント、過剰な権限、秘密情報の渡し方を誤ると、隔離の効果が弱まります。Docker公式のEngineセキュリティ資料も確認し、便利さだけで安全性を判断しないでください。

注意：読み取り専用で十分なディレクトリを読み書き可能にしないでください。特にSSH鍵、クラウド認証情報、個人用ホームディレクトリ全体のマウントは、最初の検証対象から外すのが安全です。

第二の判断軸：ローカルコードをどこまで触らせるか

「OpenHandsのローカルインストールは安全か」という問いには、インストーラーの種類だけでは答えられません。Agentが実行されるユーザー、作業ディレクトリ、マウントされたパス、外部サービス用の鍵が実際のリスクを決めます。

次の条件リストで選択してください。

• 作業対象が捨ててもよいサンプルで、まず画面を確認したいなら、デスクトッププレビュー版またはnpxを選びます。
• 変更対象を1つのリポジトリと必要な設定ディレクトリに限定したいなら、Dockerへ移します。
• ホスト側の秘密情報をAgentから見せたくないなら、ホームディレクトリ全体の直接公開を避け、専用の作業領域を作ります。
• 生成物を停止後も残したいなら、コンテナ内部ではなく、確認済みのボリュームまたはホスト側の専用ディレクトリへ保存します。
• 既存の認証情報、物理デバイス、macOS固有ツールを直接使う必要があるなら、Dockerへ無理に押し込まず、専用の実行ホストを検討します。

Docker公式のAgent Canvas用バックエンド手順を使う場合も、起動できたことだけで完了にしないでください。Agentが参照できるディレクトリ、設定の保存先、停止後のファイル、再起動後の接続を順番に確認する必要があります。

実際に導入するときの確認手順

第一歩：目的と失敗時の戻し方を決める

最初に、試したいタスクを「読み取りだけ」「テストコードの変更」「依存関係の更新」などに分けます。失敗時にリポジトリを捨てて作り直せるならローカル試用の許容範囲は広がりますが、重要なコードを直接開くならDockerまたは分離された実行ホストを優先してください。

第二歩：Canvasとバックエンドを分けて記録する

Canvasをどの端末で表示し、Agentとツールをどこで実行するかをメモします。手元のCanvasから別ホストへ接続する場合は、URL、認証方法、TLSの有無、接続元制限を一つの設定表にまとめます。

第三歩：最小の作業領域だけを渡す

最初の起動では、専用のテストリポジトリを指定します。Dockerならマウントしたディレクトリを確認し、Agentが親ディレクトリや無関係な秘密情報まで参照できないことを検証します。

第四歩：最小タスクを実行する

「作業ディレクトリの名前を表示する」「既存ファイルを読む」「小さなテストを実行する」程度のタスクから始めます。画面が表示されただけでは成功ではなく、Agentが想定したバックエンドで動き、許可したファイルだけを扱ったという証拠を残します。

第五歩：停止と再起動を試す

Canvasを閉じる、ターミナルを終了する、コンテナを停止するという順番で、どこまで処理が止まるか確認します。設定や生成物が残るべき構成なら、再起動後に同じ場所から読み出せることを確認してください。

第六歩：更新方法を固定する

デスクトッププレビュー版、npx・npm、Dockerでは更新経路が異なります。自動更新に任せるのか、固定したイメージやパッケージを検証してから更新するのかを決め、チーム利用では導入手順とロールバック方法を文書化します。

常時稼働とチーム共有ではリモートバックエンドを選ぶ

PCのスリープ、ターミナルの終了、一時的な接続切断がタスクの失敗につながるなら、バックエンドを独立したVMやリモートホストへ移す段階です。手元のCanvasは操作画面として使い、Agent、リポジトリ、開発ツール、ログを常時稼働側に置きます。

公式のVM自ホスト手順を参照するときは、単に接続できるかだけでなく、再起動後のサービス起動、作業ディレクトリの永続化、タスク状態の復旧を確認してください。公開ネットワークから接続する場合は、認証、TLS、ファイアウォールや接続元制限を追加します。

チームでは「画面を共有する」「バックエンドを共有する」「実行環境を共有する」を分けて考えてください。Linuxで完結する一般的なタスクと、macOS固有のSDK、Xcode、署名、実機接続を必要とするタスクは、同じ実行プールに押し込まず、要件ごとに分けるほうがトラブルを減らせます。macOS開発を遠隔で行う場合は、Mac miniレンタルの利用条件も、必要なツールチェーンと接続方法を確認してから比較してください。

経験上、チーム導入の失敗はインストールそのものより、誰がどのリポジトリを変更できるか、停止後に何を復元できるか、同じ環境を再作成できるかを決めないまま共有を始めることから起きます。

方式を変える前に残すべき受け入れ記録

導入後は、次の項目を環境ごとに記録してください。

• Canvasの版と、公式資料で示されたプレビュー状態
• Agentが実行されたホスト、VM、コンテナの識別情報
• 読み書き可能なディレクトリと、読み取り専用のディレクトリ
• APIキーやSSH鍵を渡していないこと、または専用資格情報を使っていること
• 停止後に残る設定、ログ、生成物、タスク状態
• 別端末からの再接続、認証失敗時の挙動、TLSと接続元制限
• Dockerイメージやnpmパッケージを更新する際のロールバック手順

個人の初回試用なら、最小タスクが成功し、対象外のファイルへアクセスできないことを確認できれば次へ進めます。チーム用途なら、同じ手順を別の担当者が再現できることまでを受け入れ条件にしてください。

まとめ：現在の方式からMac環境へ移す判断

手元のデスクトップ版やローカルDockerは、試行錯誤を始めやすい反面、ノートPCのスリープで止まりやすく、個人の権限設計に依存し、チームで同じ状態を再現しにくいという弱点があります。Linuxや一般的なコンテナ環境だけでは、Xcode、署名、macOS SDK、実機に近いApple開発環境が必要なタスクにも対応できません。

そのため、短期の検証や一時的なMac開発環境が必要なら、SSHMacのMac環境を候補に入れる価値があります。常時稼働のバックエンドが必要な場合は、まずSSHMacのヘルプセンターで接続条件と運用範囲を確認し、個人試用、リモート常駐、Appleツールチェーン利用のどれに該当するかを切り分けてください。長期間の固定負荷や物理インターフェースが必須なら自社保有機のほうが適する場合もありますが、期間限定の検証環境なら、ローカル端末を公開せずにMac側の実行基盤へ移せる構成のほうが管理しやすい場面があります。