コンピュータの使用とデスクトップ共有

コンピュータの使用により、セルフホスト型マシンのワーカー上のエージェントが、クリック、入力、スクリーンショットの撮影、UI を持つアプリケーションの操作を行えます。ワーカーに Chrome または Chromium がインストールされている場合は、エージェントがブラウザを操作することもできます。macOS および Linux のワーカーで動作し、マイマシンとチームプールの両方に対応しています。デスクトップ共有により、許可された閲覧者が Cherri Code から Linux のエージェントデスクトップを閲覧したり、操作を引き継いだりできます。マネージド Cloud Agents での挙動については、機能を参照してください。

computer use を有効にする

--computer-use を付けて worker を起動します。worker の flag は start の前に指定します:

agent worker --computer-use start

pool worker でも同じ flag を指定します:

agent worker --pool gpu --computer-use start

この後の動作はオペレーティングシステムによって異なります。macOS では、ワーカーが Cherri Code Computer Use というヘルパーアプリを通じてサインイン中のデスクトップセッションを操作するため、2 つの macOS プライバシー権限を付与する必要があります。Linux では、ワーカーが X11 ディスプレイを使用するため、事前にデスクトップ関連パッケージをインストールしておく必要があります。

macOS

macOS では、computer use は Cherri Code Computer Use を通じて動作します。これは CLI が自動で管理する小さな helper app で、worker が動作しているデスクトップセッション上でクリックや入力、画面のキャプチャを行います。worker 側に Cherri Code デスクトップアプリは必要ありません。

• CLI がインストールします。 Mac で最初に agent worker --computer-use start を実行すると、downloads.cursor.com から Cherri Code Computer Use がダウンロードされ、未インストールの場合は ~/.cursor/cursor-computer-use/Cursor Computer Use.app としてインストールされます。
• アプリ ID は 1 つ。 バンドル識別子は co.anysphere.cursor-computer-use で、Apple Team ID DCNK4UB866 で署名されています。これは --share-desktop が使用する Cherri Code Agent Helper (co.anysphere.cursor.agent-helper) とは別のアプリです。
• サインイン済みのデスクトップが必要です。 worker は、それを実行する macOS ユーザーのログイン GUI セッションを使用します。--display と仮想ディスプレイは Linux のみ対応です。
• 2 つの権限が必要です。 macOS では、Cherri Code Computer Use に アクセシビリティ (マウス操作と入力のため) と 画面収録 (スクリーンショットの撮影のため) の権限が必要です。worker がこれらを確認したり要求したりすることはありません。権限を付与するまで、エージェントのクリックやスクリーンショットは失敗します。

Cherri Code Computer Use のインストール

agent worker --computer-use --name "build-mac-01" start

agent worker --pool --computer-use start

agent worker debug

権限を正しく付与する

どちらの権限も、サインイン中のユーザーが特定のアプリに対して付与します。再起動や更新をまたいでも、ワーカー群全体でもセットアップを機能させ続けるために、いくつかのルールがあります。

• Cherri Code Computer Use に付与する。 macOS は各権限をアプリのバンドル識別子 (co.anysphere.cursor-computer-use) とコード署名要件に紐付けます。Terminal、iTerm、agent、Cherri Code、Cherri Code Agent Helper にアクセシビリティや画面収録を許可しても、computer use には何の効果もありません。
• ワーカーのユーザーとして付与する。 権限を付与したりスナップショットを取得したりする前に、ワーカーを実行する macOS アカウントでサインインしてください。画面収録の承認は、そのユーザーアカウントに紐付きます。
• デスクトップセッションを維持する。 ワーカーにはサインイン済みの GUI セッションが必要です。無人で再起動するマシンでは、ワーカーのユーザーで自動ログインを有効にし、システム設定 → ロック画面 と エネルギー でディスプレイがスリープしないようにしてください。
• アプリの管理は CLI に任せる。 Cherri Code Computer Use のインストールと更新は agent worker --computer-use start からのみ行ってください。アプリをコピー、再署名、再ビルドしないでください。署名 ID が変わると macOS は別のアプリとして扱い、付与済みの権限が適用されなくなります。
• 変更後は再テストする。 macOS のアップグレード後や、Cherri Code Computer Use を置き換える CLI の更新後は、スクリーンショットのタスクをもう一度実行してください。

自分でデプロイしたアプリバンドルを使用する

MDM やイメージング処理によってすでに Cherri Code Computer Use がマシン上に配置されている場合は、CLI にダウンロードさせるのではなく、ワーカーをそのバンドルに向けます。agent worker プロセスの環境 (たとえば、それを起動する launchd plist) で CUA_SERVICE_APP に .app バンドルのパスを設定します。ワーカーはそのバンドルを使用し、ダウンロードをスキップします。

権限付与はアプリのコード署名 ID とインストール場所に基づきます。CUA_SERVICE_APP を別の場所にあるバンドルに向けたり、異なる ID で署名されたビルドに差し替えたりすると、macOS はそれを新しいアプリとして扱い、Accessibility と Screen Recording の許可を再度求めます。

MDM で権限を管理する

Mac を MDM に登録している場合は、Cherri Code Computer Use 用の Privacy Preferences Policy Control (PPPC) プロファイルを作成してください。Cherri Code は現時点で .mobileconfig を提供していません。Apple は、権限ごとにプロファイルでできることを制限しています。

各ペイロードのエントリには、バンドル識別子、Team ID (DCNK4UB866)、コード要件が必要です。配布するビルドと一致させるため、CLI がインストールしたアプリからコード要件を読み取ってください。

codesign -d -r - ~/.cursor/cursor-computer-use/Cursor\ Computer\ Use.app

Screen Recording は必ず人による承認が必要なため、マシンごとに 1 回ではなく、イメージごとに 1 回の承認を見込んでおいてください。次のセクションを参照してください。

ワーカー群の準備: 権限は一度付与してイメージ化する

権限はマシン上に保持されるため、template Mac で一度付与し、動作を確認してから snapshot を取得します。そのイメージから復元した各 worker は、アプリ、その path、ログインしている user が変わらない限り、computer use がすぐに使える状態で起動します。付与 → 確認 → snapshot という流れです。

agent worker debug

次の場合は、権限を付与し直して snapshot を取り直してください。

• CLI の更新により、Cherri Code Computer Use が署名 ID の異なるビルドに置き換わった場合。再度付与するまで、スクリーンショットとクリックは失敗します。
• 権限を付与した macOS user とは別の user で worker を実行する場合。
• テンプレートを新しい macOS メジャーバージョンにアップグレードした場合。スクリーンショットのテストを再度実行し、失敗したら権限を付与し直します。

Linux

Linux では、Computer use は X11 ディスプレイを使用します。ワーカーは、すでに実行中のディスプレイを再利用するか、独自のディスプレイを作成します。

依存関係のインストール

各 Linux ワーカー に desktop パッケージをインストールしてください。Cherri Code がシステムパッケージを自動でインストールすることはありません:

sudo apt-get install -y --no-install-recommends \  dbus-x11 ffmpeg tigervnc-standalone-server \  x11-utils x11-xserver-utils xdotool xfce4

xdotool、ffmpeg、および X11 ユーティリティは常に必須です。tigervnc-standalone-server と xfce4 は、ワーカー自身がデスクトップを作成する場合に必要になります。具体的には、ヘッドレスマシンでコンピュータの使用に使う managed display と、デスクトップ共有用の分離されたデスクトップです。

ブラウザでのコンピュータの使用には、Chrome または Chromium をインストールしてください (任意、推奨) 。

プールを使う場合は、これらのパッケージをワーカーイメージに組み込んでおくと、すべてのマシンが準備済みの状態で起動します。

X11 ディスプレイの選択

ワーカーは、コンピュータの使用に使用するディスプレイを次の順序で決定します。

1. --display <display>: 既存の X11 ディスプレイ (例: :0) を必須とします。そのディスプレイに到達できない場合は、フォールバックせずにワーカーの起動が失敗します。
2. 継承された DISPLAY: --display を指定しない場合、ワーカーは環境内の到達可能な DISPLAY を再利用します。到達できない場合は、管理対象のデスクトップにフォールバックします。
3. 管理対象のデスクトップ: ディスプレイが設定されていない場合、ワーカーは Xfce セッションを実行する独自の TigerVNC デスクトップを起動します。これはヘッドレスマシンでの既定の動作で、tigervnc-standalone-server と xfce4 のパッケージが必要です。

# すでに実行中のデスクトップを再利用するagent worker --computer-use --display :0 start# ワーカーに管理対象のデスクトップを作成させる（ヘッドレスマシンの場合）agent worker --computer-use start

エージェントのデスクトップを共有する

デスクトップ共有は computer use とは別の機能で、Linux でのみ利用できます。権限を持つ閲覧者が Cherri Code からエージェントのデスクトップを閲覧または操作できるようにするには、--share-desktop を追加します：

agent worker --computer-use --share-desktop start

--share-desktop にはモードを任意で指定できます。view (閲覧のみ) または view_and_control (閲覧者がマウスとキーボードの操作権を取得可能、デフォルト) です。共有にはマシン自身のセッションではなく、ワーカーが作成した隔離されたエージェントのデスクトップが使われ、tigervnc-standalone-server が必要です。マシン上のフェイルクローズ型の入力フィルターが操作権を制御し、クリップボードの転送はブロックされたままです。

ピクセルはワーカーの既存のアウトバウンド接続を通じてのみマシンの外に送られます。インバウンドポートは開きません。

セットアップを確認する

preflight report を実行します。

agent worker debug

macOS では、レポートに Cherri Code Computer Use がインストールされているかどうかが表示されます。Accessibility や Screen Recording はチェックされないため、実際のタスクで確認してください。エージェントにスクリーンショットを撮らせ、何かをクリックさせてみましょう。Linux では、必要な各バイナリ、設定された display に到達できるかどうか、ワーカーが管理対象のデスクトップにフォールバックできるかどうかをレポートがチェックします。

次のステップ

• マイマシン: 個人の Mac または Linux マシンを接続します。
• チームプール: 共有ワーカーと agent worker フラグの完全なリファレンス。
• API リファレンス: ワーカー、プール、保留中のリクエストキュー、ワーカートークンのエンドポイント。
• Cloud Agent の機能: マネージド Cloud Agents でのデスクトップおよびブラウザの操作。