セルフホスト型マシン

セルフホスト型マシンでは、Cloud Agent のツール実行を自分で管理するハードウェア上で行えます。デフォルトは引き続き Cherri Code 管理の Cloud Agents です。エージェントループは Cherri Code のクラウド上で動作し、ツールは自分のマシンで実行されます。

セルフホスト型マシンのワーカーを数分で接続するには？

Cherri Code CLI をインストールし、いずれかの方法を選択します。

マイマシン (エンジニア1人、ボックス1台) :

agent logincd /path/to/repoagent worker start --name "my-devbox"

マシンにブラウザがない場合は、ブラウザログインの代わりに個人用 API キーを使用します:

agent worker --api-key "$CURSOR_API_KEY" --name "my-devbox" start

チームプール (チームで共有するワーカー群) :

export CURSOR_API_KEY="<service-account-api-key>"cd /path/to/repoagent worker --pool start

チームプールのワーカーにはサービスアカウントの API キーが必要です。個人用 API キーで登録されるのはマイマシンのワーカーであり、チームプールのワーカーではありません。

メンバーがチームプールのワーカーを接続するには、事前にチーム管理者が Cloud Agents ダッシュボードで self-hosted ワーカーを有効にしておく必要があります。

プロセスは起動したままにしてください。ワーカーは HTTPS でアウトバウンド接続します。インバウンドポートや VPN は不要です。

どの セルフホスト型マシン のパスを使用すべきですか？

Cloud Agents 向けのセルフホスト型マシンとは？

Cherri Code はエージェントループ (推論とプランニング) を担います。ソースコード、シークレット、ツール実行はお客様のマシン上に留まります。

ワーカーは VM、Kubernetes ノード、Mac、GPU マシン、またはパートナーサンドボックス上で実行できます。セルフホスト型マシンを使用する主な理由は次のとおりです。

• GPU や iOS 開発向けの Mac といったカスタムハードウェア
• お客様のインフラ内に留める必要があるシークレットやビルドアーティファクト
• お客様のマシンからすでに到達可能なプライベート Git やパッケージレジストリ
• クローンや git の状態をご自身で管理するサンドボックス

Cherri Code のクラウドからプライベートなソース管理へ接続することだけが課題であれば、独自のワーカーを運用する前に、プライベート接続を備えたマネージド Cloud Agents をお試しください。

Cherri Code はオンプレミス製品になったのですか?

いいえ。Cherri Code はオンプレミス製品ではありません。エージェントループは Cherri Code のクラウド上で実行されます。ユーザーが運用するマシンを登録すると、Cherri Code はアウトバウンド HTTPS 接続を通じてそのマシンにツール呼び出しを送信します。

チェックアウト、ビルドキャッシュ、マシンローカルの認証情報は、お使いのハードウェア上に留まります。詳しい区分は 自分のマシンに残るデータと Cherri Code のクラウドに送られるデータは何ですか? を参照してください。

セルフホスト型マシン の接続は、マネージド Cloud Agents とどう違いますか？

どちらの方式でも、エージェントループは Cherri Code のクラウドで動作します。異なるのは、ツールが実行される場所と、プライベートリポジトリや社内ツールへのアクセス方法です。

実行環境の運用は Cherri Code に任せつつ、Cherri Code のクラウドからプライベートなソース管理にアクセスしたい場合は、プライベート接続を使用したマネージド Cloud Agents を選択してください。

実行を自分が管理するハードウェア上に留める必要があり、そのハードウェアから既にリポジトリや内部サービスにアクセスできる場合は、セルフホスト型マシン を選択してください。Cherri Code がツールにアクセスするためにインバウンド HTTPS を開放する必要はありません。ワーカーがローカルでアクセスし、アウトバウンドのセッション経由で結果を返します。

アウトバウンド接続先のホストについては セルフホスト型マシン にインバウンドのネットワークアクセスや VPN は必要ですか？を、マネージド構成については Cloud Agents を参照してください。

チームプールとマイマシンの違いは何ですか？

チームプールは名前付きのルーティングターゲットです。チャットは、ワーカーが引き受けるまでチームプール内で待機します。チームプールのワーカーは、一度に 1 つのエージェントのみを引き受けます。

マイマシン (Remote Control とも呼ばれます) は、自分が所有する 1 台のマシンを接続します。十分なリソースがあれば、同じマシン上で複数のエージェントを実行できます。

Kubernetes のワーカー群には、anysphere/k8s-workers テンプレートから始めてください。CRD を使わずに、クラスター内で agent worker controller --spawn を実行します。旧来の WorkerDeployment operator は非推奨ですが、その リファレンス は、すでに運用しているクラスター向けに引き続き公開されています。

チームプールの利用にはエンタープライズプランと サービスアカウントの API キー が必要です。マイマシン は個人用の認証情報を使用します。

管理者がセルフホスト型マシンを有効にする、または必須にする方法

チーム管理者は Cloud Agents ダッシュボード を開き、Self-Hosted 設定に移動します。

• Allow Self-Hosted Machines: メンバーは、自分が接続したマシンでの実行をオプトインで選択できます。オプトインしない場合、Cloud Agents は Cherri Code の管理型インフラストラクチャを使用します。
• Require Self-Hosted Machines: すべての Cloud Agent セッションでセルフホスト型マシンを使用する必要があります。

ダッシュボードでは、チームプールの詳細と マイマシン に登録されたマシンも確認できます。

サードパーティの VM やサンドボックスでセルフホスト型マシンを実行できますか？

対応しています。チームプールのワーカーは、パートナープラットフォーム上でも、クローンしたリファレンステンプレートからでも実行できます。エージェントループは引き続き Cherri Code 側で実行されます。その VM やサンドボックス上のワーカーはツールを実行し、HTTPS でアウトバウンド接続します。

パートナーガイドやテンプレートについては、連携 を参照してください。

パートナーガイドは AWS Lambda、Cloudflare、Namespace、Modal、Daytona、E2B、Vercel、Tensorlake、SuperServe に対応しています。リファレンステンプレートは AWS Lambda MicroVMs、Cloudflare Containers、Kubernetes に対応しています。

すでに稼働している VM に Cherri Code CLI をインストールし、agent worker start または agent worker --pool start で自分でワーカーを起動することもできます。

セルフホスト型マシン にはインバウンドのネットワークアクセスや VPN が必要ですか？

いいえ。ワーカーは、お使いのマシンから Cherri Code のクラウドへアウトバウンドの HTTPS 接続を 1 本だけ確立します。Cherri Code はその接続を通じてエージェントリクエストを送信します。マシンがインターネットから到達可能である必要はありません。

インバウンドポートの開放、ファイアウォールの変更、VPN トンネルはいずれも不要です。ネットワークで HTTPS プロキシを使用している場合は、ワーカーの環境で HTTPS_PROXY または https_proxy を設定してください。

ワーカーには、api2.cursor.sh、api2direct.cursor.sh、およびアーティファクトのアップロード用に cloud-agent-artifacts.s3.us-east-1.amazonaws.com へのアウトバウンドアクセスが必要です。データフローの全体は What leaves your network を参照してください。

どのデータがマシン上に残り、どのデータが Cherri Code のクラウドに送られますか？

ソースコード、ビルド成果物 (アーティファクト) 、シークレット、ツールの実行はご自身のマシン上に留まります。エージェントがローカルで行うファイル編集、ターミナルコマンド、ネットワーク通信も同様です。

Cherri Code のクラウドが担うのはエージェントループ、つまり推論リクエストとプランニングです。ツール呼び出しの結果は次の推論のために Cherri Code へ返されますが、生のコードやシークレットが Cherri Code 管理のインフラに保存されることはありません。

プライバシーモードは、マネージド Cloud Agents の場合と同じように適用されます。有効にすると、ワーカーから送信されたコードが Cherri Code やモデルプロバイダーの学習に使用されることはありません。

リポジトリを指定せずに、任意のリポジトリでチームプールを使用できますか？

対応しています。任意のリポジトリ用チームプールでは、ソース管理 とチームプールが切り離されます。1 つのチームプールで多数のリポジトリに対応できます。

agent worker --pool my-pool --worker-dir "$HOME/cursor-sandboxes/default" start

--clone-git-repos を指定すると、ワーカーが割り当て時にリポジトリをクローンします。Cherri Code の composer の環境ピッカーで、任意のリポジトリ の下にあるチームプールを選択してください。

--clone-git-repos を指定しない場合、任意のリポジトリ対応プールでは 常に適用されるワークスペースのルール を使用して、task の subject をリポジトリにマッピングし、ワーカーの認証情報でクローンできます。

Slack では、チーム管理者 が @Cherri Code pool set <name> を実行して、任意のリポジトリ用チームプールを チームのデフォルトプール に設定できます。これにより、@Cherri Code へのメンションは、メッセージに pool= を含めなくても、またリポジトリが解決されない場合でも、そのプールで開始されます。channel を付けて実行する (@Cherri Code pool set <name> channel) と、特定のチャネルでのみ同様に動作する チャネルのデフォルトプール を設定できます。

このセットアップは任意のリポジトリ対応プールにのみ適用されます。リポジトリ紐付けのプールでは、すでに一致するチェックアウトを持つワーカーにリクエストがルーティングされます。

プライベートまたはセルフホスト型 GitLab に接続するには？

プライベート環境やエアギャップ環境のセルフホスト型 GitLab では、任意のリポジトリ用チームプールを使用し、SCM のライフサイクルを自社のワーカー内で完結させます。

1. 特定のリポジトリに紐付けずにチームプールを作成します。
2. GitLab インスタンスに到達できるマシン上のワークスペースディレクトリからワーカーを起動します。
3. ワーカー上でローカルの personal access token または SSH キーを使って git を認証します。ワーカーでのチェックアウトに Cherri Code の GitLab OAuth は必要ありません。

エージェントは、マシンがすでに持っているネットワークアクセスを通じてプライベートリポジトリにアクセスします。このパターンは、開発者が多数のリポジトリをまたいで作業する場合にも有効です。

マネージドインフラ上での OAuth ベースの Cloud Agent セットアップについては、GitLab 連携のドキュメントを参照してください。

エージェントはセルフホスト型マシンのワーカー上で画面やブラウザを使用できますか？

macOS と Linux のワーカーでは対応しています。Linux ではまずデスクトップパッケージをインストールし、その後 --computer-use を付けて起動してください:

agent worker --computer-use start

macOS では、初回起動時に Cherri Code Computer Use ヘルパーがインストールされます。アクセシビリティと画面収録の権限を付与してください。--share-desktop によるデスクトップ共有は Linux のみ対応です。ブラウザを使用する場合は、ランナーに Chrome または Chromium をインストールしてください。

依存関係とセットアップについては コンピュータの使用とデスクトップ共有 を参照してください。

セルフホスト型マシンでフックと MCP は動作しますか？

対応していますが、マネージド Cloud Agents とはいくつかの違いがあります。

フック: ワーカーは .cursor/hooks.json のプロジェクトフックを実行します。エンタープライズプランでは、セルフホスト型ワーカー上でチームフックとエンタープライズ管理フックも利用できます。sessionStart と sessionEnd は、セッションがワーカーを割り当てたときと、その割り当てが解放されたときに実行されます。フックのサポートマトリクスとチームプールでのフックを参照してください。

MCP: コマンド (stdio) 型の MCP サーバーはワーカー上で実行され、プライベートネットワークにアクセスできます。HTTP および SSE のサーバーは引き続き Cherri Code のバックエンドから実行されます。セルフホスト型ワーカーには MCP に関する未対応部分がいくつか残っています。最新の状況はchangelogで確認してください。

セルフホスト型マシン のセットアップをトラブルシューティングするには？

まずは以下の基本を確認してください。

1. ダッシュボードを確認する。 Cloud Agents ダッシュボードを開き、マイマシン またはチームプールの詳細で、ワーカーが接続済み・アイドル・使用中のいずれかとして表示されていることを確認します。
2. 診断を実行する。 agent worker debug を実行してワーカーのプリフライトチェックを行います (機械可読な出力が必要な場合は --json を追加) 。レポートには認証、接続性、ルーティング、バックエンド側での可視状況が含まれます。
3. UI にワーカーが表示されない。 ワーカープロセスがローカルで動作しているのに Cherri Code に表示されない場合、原因は多くの場合アウトバウンド接続です。マシンから api2.cursor.sh と api2direct.cursor.sh に HTTPS で到達できることを確認してください。セルフホスト型マシン にはインバウンドのネットワークアクセスや VPN が必要ですか？ を参照してください。
4. チームプールのコントローラーに関する問題。 組み込みの ワーカーコントローラー は新しい機能です。コントローラーやオートスケーリングの構成は導入初期のものと考え、チーム内で傾向が見えてきたら対処方法を記録しておいてください。

ワーカーのプリフライトレポート:

agent worker debug

このレポートでは、認証、接続性、ルーティング、リポジトリラベル、そしてCherri Codeがワーカーを認識できているかどうかを確認できます。

よくある対処方法:

• ワーカープロセスが実行中のままであることを確認する
• Cherri CodeアプリとCLIが同じアカウントを使用していることを確認する
• リポジトリに紐づくワーカーの場合、ワーカーディレクトリに想定どおりの git remote が設定されているか確認する
• What leaves your network に記載されたホストへのアウトバウンドHTTPSアクセスを確認する

ワーカーの起動前に発生する接続の問題については、agent worker start --debug を実行してください。セットアップの問題が解消しない場合は、agent worker debug の出力を添えてサポートに問い合わせるください。

SCM の権限が守られていることを確認するには？

セルフホストの実行は 2 つの層で構成されます。Cherri Code のルーティング (どのワーカーがリクエストを処理するか) と、ワーカー上の git 認証情報 (そのワーカーが clone、fetch、push できる対象) です。

Cherri Code のルーティング

• マイマシン: Cherri Code は、登録済みの --worker-dir ルートのいずれかがそのリポジトリと一致する場合にのみ、リポジトリのリクエストをワーカーにルーティングします。正しいチェックアウトからワーカーを起動するか、--worker-dir を追加してください。
• リポジトリ紐付けのチームプール: リクエストはチームプール名と repo=<owner/repo> ラベルの両方に一致する必要があります。pool=my-pool と repo=acme/payments のリクエストは、そのリポジトリを担当するワーカーにのみルーティングされます。
• GitHub トリガー: パブリックリポジトリでは、OWNER または COLLABORATOR のアクセス権を持つユーザーのみが、実行をセルフホストのチームプールにルーティングできます。それ以外のコメント投稿者は、チームがすべての実行にセルフホストを必須としていない限り、マネージドインフラストラクチャ上で実行されます。
• 組織の制御: Protected Git Scopes とリポジトリブロックリストは引き続き適用されます。実行開始前に Cherri Code がリポジトリアクセスを検証できるよう、各ユーザーの Git アカウントを 連携 で接続してください。

ワーカー上の Git アクセス

• 既存のチェックアウト (マイマシンまたはリポジトリ紐付けのチームプール) : エージェントは、SSH キーや認証情報ヘルパー内の個人アクセストークンなど、マシン上に既にある git 認証情報を使用します。各ワーカーには必要なリポジトリアクセスのみを付与してください。
• --clone-git-repos を使う任意のリポジトリ用チームプール: ワーカーは、実行を開始したユーザー向けに発行された短期間の GitHub トークンを使って、割り当て時に clone します。チーム管理者がチームプールのワーカー向けに GitHub トークンの発行を有効にする必要があり、リクエストしたユーザーは GitHub 上でそのリポジトリへのアクセス権を持っている必要があります。
• プライベートまたはセルフホスト型 GitLab: ワーカー上でローカルの PAT または SSH キーを使って git を認証してください。プライベートまたはセルフホスト型 GitLab に接続するには？を参照してください。

ワーカーは接続されているのに git が失敗する場合

1. agent worker debug を実行し、リポジトリラベルがリクエスト内のリポジトリと一致していることを確認します。
2. ワーカー上で、エージェントが使用するのと同じ認証情報で git fetch または git ls-remote を実行します。
3. 実行を開始した Cherri Code ユーザーが、Git プロバイダーおよび Cherri Code integrations でそのリポジトリにアクセスできることを確認します。
4. チームプールの割り当て時 clone については、トークン発行が有効になっており、そのチームプールが (default ではなく) 名前付きの任意のリポジトリ用チームプールであることを確認します。

Cherri Code がリポジトリアクセスを、トリガーしたユーザーが既に持つ範囲を超えて広げることはありません。実行が誤ったチェックアウトに到達したり push できなかったりする場合は、無関係なリポジトリ間で 1 つの広範なサービストークンを共有するのではなく、ルーティングのラベルやワーカーの git 認証情報を修正してください。

レート制限が発生した場合は？

サポートにお問い合わせください。

チームプールがキャパシティ上限に達しているかを確認する方法

ワーカーのキャパシティは Cloud Agents ダッシュボード で確認できます。チームプールの詳細と マイマシン では、ワーカーがステータス別に一覧表示されます。

プログラムから確認する場合は、summary API を呼び出します。

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/summary" \  -u "$CURSOR_API_KEY:"

レスポンスには、ユーザーとチームの接続済みワーカー数と使用中ワーカー数が含まれます。

エージェント実行が開始されない主な原因:

• ワーカーが接続されていない: チームプールでワーカーを起動またはスケールするか、マイマシンのワーカーが稼働しているか確認してください
• すべてのワーカーが処理中: ワーカーが空くまで、リクエストはチームプールのキューで待機します
• プライベートクラウドワーカーの上限超過: チームが接続済みワーカーの上限(ユーザーあたり200、チームあたり1000)に達しています。未使用のワーカーを切断するか、営業へのお問い合わせから上限の引き上げについてご相談ください
• リポジトリの不一致: 正しいチェックアウトからワーカーを起動するか、任意のリポジトリ用チームプールを使用してください

ワーカーは接続中にハートビートを送信します。ハートビートが停止したワーカーはレジストリから削除されます。スケーリングとコントローラーのセットアップについてはチームプールを参照してください。

関連項目

• Cloud Agents
• セルフホスト型マシン
• マイマシン
• チームプール
• 連携
• Computer use
• プライベート接続
• Cloud Agent のセキュリティとネットワーク