チームプール

プールは、リクエストを セルフホスト型マシン のワーカーに接続する、名前付きのルーティング先です。リクエストは、空きワーカーが引き受けるまでプール内で待機します。GPU が必要な作業用と Mac が必要な作業用でプールを分けるなど、実行環境ごとに個別のプールを作成してください。

チームプールは、Cloud Agents を自社管理のインフラ内で実行したい Enterprise チーム向けの機能です。各開発者が個人のマシンでワーカーを起動する代わりに、管理者がワーカーのプールを運用し、組織内のエージェントに割り当てます。

プールは、インフラを誰が所有・管理するかという選択肢です。これによってエージェントループが Cherri Code のクラウド外に移るわけではありません。ワーカーは、お客様のインフラ内でターミナルコマンド、ファイル編集、ブラウザ操作、その他のツール呼び出しを実行し、Cherri Code はオーケストレーション、モデルアクセス、Cloud Agent の利用体験を担います。

次のような場合はプールを使用します:

• チームまたは組織向けにワーカーを一元管理したい
• 個人ごとのブラウザログインではなく、サービスアカウント認証を使いたい
• Kubernetes、オートスケーリング、または一元管理されたキャパシティが必要
• 作業を適切な環境、チーム、リポジトリ、またはハードウェアプロファイルに振り分けるラベルが必要
• ツール実行、ビルド出力、ワーカーログ、監視を会社所有のホストで行いたい

すばやく個人用にセットアップするには、マイマシン を参照してください。プールに必要なプラン、資格情報、ダッシュボード設定、マシンの依存関係については、セルフホスト型マシンの概要にある 要件 を参照してください。

仕組み

ワーカーは、Cherri Code のクラウドに対して長時間維持されるアウトバウンド HTTPS 接続を確立します。推論やプランニングを含むエージェントループは Cherri Code のクラウドで実行され、この接続経由でツール呼び出しを送信します。ワーカーは、それらのツール呼び出しをお客様のインフラ内で実行します。これには、ターミナルコマンド、ファイル編集、ブラウザ操作、内部サービスへのアクセスが含まれます。

リポジトリ、ビルドキャッシュ、シークレット、ツール実行は自分の環境内にとどまり、オーケストレーション、モデルアクセス、Cloud Agent の利用体験は Cherri Code が担います。スクリーンショットや動画などの Cloud Agent のアーティファクトは Cherri Code にアップロードされ、PR やダッシュボードで確認できます。

ワーカーに必要なのはアウトバウンドアクセスだけです。インバウンドポート、パブリック IP、VPN トンネルは不要です。必要なホストの一覧は、ネットワークを参照してください。

前提条件

• Cherri Code Enterprise プラン
• Cloud Agents ダッシュボードでチーム管理者により設定されたセルフホスト設定:
  • Allow Self-Hosted Machines を有効にすると、ユーザーはセルフホスト実行を選択できます。
  • Require Self-Hosted Machines を有効にすると、すべての Cloud Agent の実行がセルフホスト ワーカーに振り分けられます。
• プールワーカー認証用のサービスアカウントの API キー
• 以下を備えたワーカーマシンまたはイメージ:
  • agent CLI がインストールされている
  • git がインストールされ、PATH から利用できる (ワーカーが git remote を扱う場合や --clone-git-repos を使用する場合に必要。独自のスクリプトで SCM を処理する場合、任意のリポジトリ対応プールでは任意)
  • ワークスペースディレクトリ (リモートが設定されたクローン済みリポジトリ、または任意のリポジトリ用ディレクトリ)
  • エージェントが必要とするビルドツール、パッケージレジストリ、シークレット、内部サービスへのアクセス

CLIをインストール

# macOS、Linux、WSL# Windows PowerShellirm '# | iex

CLI が利用可能か確認します:

agent --version

ワーカーの認証

プールワーカーの認証には、サービスアカウントの API キー、またはそのキーから単一のクレーム用に発行したセッショントークンを使用します。

ユーザー API キー、個人用 API キー、チーム API キー、組織の API キーでは、プールワーカーを起動できません。マイマシン上の個人ワーカーでは、個人用 API キーまたはユーザー API キーを使用してください。

export CURSOR_API_KEY="your-service-account-api-key"

キーは直接渡すこともできます：

agent worker --api-key "your-service-account-api-key" start

プールワーカーを起動する

ワーカーが担当する ワークスペース (Gitリポジトリのルート、または any-repo ディレクトリ) でワーカーを実行します:

cd /path/to/repoagent worker --pool start

--pool は、プールへの割り当て用に ワーカー を登録します。名前を任意で渡すと、名前付きプールに参加します (例: --pool my-pool)。名前を省略した場合、ワーカーは default に参加します。各 Cloud Agent session は、一度に 1 つのワーカー を確保します。

オーケストレーション環境では、作業完了後に process が正常に終了するよう、--idle-release-timeout と組み合わせて使用してください。

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout は、セッション終了後もしばらくの間 (秒単位) ワーカー を起動したままにして、フォローアップメッセージを処理できるようにします。デフォルトは 3600 秒です。リリースと再接続の仕組みについては セッションのライフサイクル を参照してください。

computer use を有効にする

--computer-use を渡すと、claim されたエージェントが worker 上でクリック、入力、スクリーンショットの撮影、アプリの操作を行えるようになります:

agent worker --pool my-pool --computer-use start

macOS では、初回起動時に Cherri Code Computer Use ヘルパーアプリがインストールされます。Accessibility と Screen Recording の権限を付与し、スクリーンショットを撮るタスクで動作を確認したうえでマシンをスナップショットしておくと、イメージから復元されたすべてのワーカーがすぐに使える状態になります。Linux では、デスクトップパッケージをワーカーイメージに組み込んでください。macOS の権限設定の手順、MDM プロファイルのガイダンス、Linux のディスプレイオプションについては、コンピュータの使用とデスクトップ共有を参照してください。

複数のリポジトリルートを登録する

セルフホストのマルチリポジトリ対応は、ワーカーの起動時に複数のワークスペースルートを登録して設定します。ローカルの各リポジトリルートごとに --worker-dir を 1 回ずつ指定してください。最初のルートは、割り当て ID とダッシュボード表示に使われるプライマリリポジトリになります。すべてのルートはエージェントの実行時から参照でき、有効な git origin を持つルートはリポジトリのルーティング用メタデータを登録します。

--worker-dir は最大 20 個のパスまで繰り返し指定できます。各パスは、あらかじめ存在するディレクトリである必要があります。--worker-dir を指定しない場合、CLI は現在の作業ディレクトリを使用します。

開始する前に、Dashboard > Cloud Agents > Self-Hosted でセルフホスト型ワーカーを有効にしてください。独自のマシンイメージで別の書き込み可能な場所が保証されていない限り、$HOME 配下の書き込み可能なパスを使用してください。

セットアップ例:

export WORKER_ROOT="$HOME/cursor-repos/my-org"mkdir -p "$WORKER_ROOT"git clone [email protected]:my-org/app.git "$WORKER_ROOT/app"git clone [email protected]:my-org/infra.git "$WORKER_ROOT/infra"export CURSOR_API_KEY="<key>"

ワーカー を開始する前に、事前チェックを実行します:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  debug --json

同じルートを使ってワーカーを起動します:

agent worker \  --pool my-pool \  --name app-infra-worker \  --worker-dir "$WORKER_ROOT/app" \  --worker-dir "$WORKER_ROOT/infra" \  start --verbose

ワーカーのオプションは start または debug の前に指定します。systemd、tmux、launchd、Kubernetes、または独自のプロセスマネージャーなどのスーパーバイザーの下で、プロセスを実行したままにしてください。

詳細な起動ログは、登録されたルートを確認するための確かな情報源です。正常に動作している multi-repo ワーカーでは、派生した各 repo のラベル、ワークスペースのパス、repository の URL が表示されます。

repo=my-org/apprepo=my-org/infraworkspacePaths: [app, infra]x-repository-urls: ["[email protected]:my-org/app.git","[email protected]:my-org/infra.git"]

ダッシュボードとトリガーでマルチリポジトリ ワーカーを見分けやすくするには、--name と --pool <name> を使用します。

プール モードでは、一度に 1 つの Cloud Agent だけがワーカーを取得します。--pool がない場合は、共有割り当てが許可されます。オーケストレーターで /healthz、/readyz、/metrics が必要な場合は、start の前に --management-addr 0.0.0.0:8080 を追加してください。

Git 管理外のディレクトリも実行ルートにできますが、リポジトリ ルーティング用のメタデータには反映されません。マルチリポジトリ ワーカーの場合は、ワーカーの起動前に各リポジトリをクローンしてください。空のワークスペースから開始し、割り当て後にワーカーがソース管理をブートストラップするようにするには、任意のリポジトリ対応プールを使用してください。

任意のリポジトリ対応プール

プールにはリポジトリ設定が 2 種類あります。リポジトリに紐づくプールは、プールを 1 つ以上のリポジトリに紐付けます。リクエストは repo=<owner/repo> ラベルを持ち、そのリポジトリを扱うワーカーにマッチし、ダッシュボードではそのリポジトリの下に表示されます。任意のリポジトリ対応プールでは、ソース管理はユーザー側に委ねられます。リクエストはプール名のみでマッチし、プールはダッシュボードの 任意のリポジトリ の下に表示されます。

ソース管理を自分で行いたい場合は、リポジトリを紐付けずにプールを作成してください。プールワーカーに git remote は不要です。エージェント (あるいは独自のイメージ、フック、スクリプト) にクローンと git の状態を管理させたい場合は、--worker-dir に任意の既存ディレクトリを指定してください:

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

すべての任意のリポジトリ用リクエストにリポジトリの手順を渡すには、--worker-dir に指定したディレクトリ内の .cursor/rules 配下に .mdc ファイルを作成してください。ファイル名は任意です。この例では repo-info.mdc を使用しています:

---alwaysApply: true---この任意のリポジトリ用ワーカーは、認証済みの `gh` CLI を使って`github.acme.internal` からクローンできます。- 支払い、請求、チェックアウトに関するリクエストでは  `platform/payments-service` を使用してください。存在しない場合は次を実行します:  `GH_HOST=github.acme.internal gh repo clone platform/payments-service`- メンバーポータルやアカウント設定に関するリクエストでは  `web/member-portal` を使用してください。存在しない場合は次を実行します:  `GH_HOST=github.acme.internal gh repo clone web/member-portal`- リクエストに必要なリポジトリのみをクローンしてください。以降のコマンドは  クローンしたリポジトリ内で実行してください。- リクエストに一致するマッピングがない場合は、リポジトリが設定されていないと  報告してください。リポジトリ名、クローン URL、認証情報を推測しないでください。

alwaysApply: true を設定すると、すべてのリクエストにそのルールが含まれます。クローン前から利用できるよう、ファイルはワーカーディレクトリに置き、例のマッピングは自分のリポジトリと SCM のコマンドに置き換えてください。

ワーカーを割り当てる際にワーカーが割り当て済みエージェントのリポジトリをチェックアウトするようにするには、--clone-git-repos を渡します。これはオプトインです。任意のリポジトリ対応プールのデフォルト挙動ではクローンしません。

agent worker --pool my-pool --clone-git-repos start

--clone-git-repos は --mint-github-token を含意します。クローンとフェッチには、この発行された短期 GitHub トークンが使用されます。チーム管理者が チームプール ワーカー向けに GitHub トークンの発行を有効にしておく必要があり、また git が PATH 上にある必要があります。

このフラグは任意のリポジトリ対応プールワーカーでのみ使用してください。つまり、default 以外の名前付き --pool を指定し、リポジトリのバインド (repo=) もマシンのバインド (name=) もないワーカーです。リポジトリにバインドされたワーカー、名前付きマシン、default プール、または個人の マイマシン ワーカーでは、CLI は明確なエラーを表示して終了します。

ブランチ名は --branch でクローンされます。40 文字のフルコミット SHA を指定した場合は、クローン後に detached チェックアウトを行います。発行されたトークンで認証できるよう、HTTPS の GitHub リモートを使用してください。

ワーカーディレクトリ、またはその直下のフォルダーに、割り当て済みリポジトリのクリーンなチェックアウトがすでにある場合、ワーカーは再度クローンせずにそれを再利用します。その際、チェックアウトの origin リモートが同じホストと owner/repo を指している必要があります。ワーカーは要求されたブランチ、タグ、またはコミットをフェッチしてチェックアウトします。ローカルブランチの更新は fast-forward のみです。チェックアウトを安全に更新できない場合は、代わりにチェックアウトと同じ階層に新しいフォルダーを作成してクローンします。たとえば、チェックアウトが次のような状態の場合です:

• 追跡対象ファイルに未コミットの変更がある
• 要求されたブランチに、リモートにないローカルコミットがある
• merge、rebase、cherry-pick、revert、または bisect が進行中である
• サブモジュールが設定されている
• 新規クローンにはない Git の設定やフックがある

再利用には git 2.26 以降が必要です。それより古い git では、ワーカーは常にクローンします。各チェックアウトを再利用したかどうかとその理由は、ワーカーのログに記録されます。

割り当てが終了すると、ワーカーはその割り当てのためにクローンしたリポジトリを削除し、再利用したチェックアウトは残します。割り当てのたびに大きなリポジトリをクローンしないようにするには、ワーカーを起動する前にワーカーディレクトリへクローンしておいてください。

クローンに失敗した場合、リクエストはキューに残ります。オペレーターには汎用的なクローン失敗が表示されます。

--clone-git-repos、--mint-github-token、--sync-dashboard-secrets は、コンテナまたは OS ユーザーごとにワーカーが 1 つであることを前提としています。同一ユーザー配下に認証情報を有効にしたワーカーを複数配置する構成はサポートされていません。

任意のリポジトリ対応プールでは repo= ルーティングラベルを省略します。これらのプールでエージェントを開始するには、env.type: "pool" と、プール名を設定した env.name を指定し、repos は省略してください (Create An Agent を参照してください) 。cursor.com/agents の 任意のリポジトリ からプールを選択してください。Slack では、任意のリポジトリ対応プールを チームのデフォルトプール または チャネルのデフォルトプール に設定しておくと、メッセージやデフォルトからリポジトリが特定できない場合でも @Cherri Code がエージェントを開始できます。

プールの管理

プールは永続的です。最後のワーカーが切断された後もプールは登録された状態で選択可能なままなので、ゼロまでスケールダウンし、リクエストが届いたときにキャパシティを戻せます。新しいプール名でワーカーを起動すると、プールが暗黙的に作成されます。プールを事前に管理するには Cloud Agents API を使用します。

• POST /v0/private-workers/pools は、ワーカーが接続する前にプールを事前登録します。リポジトリに紐づくプールの場合は repoOwner、repoName、repoUrl を含め、任意のリポジトリ対応プールの場合は省略します。
• GET /v0/private-workers/pools は、接続中および使用中のワーカー数とあわせてプールを一覧表示します。
• DELETE /v0/private-workers/pools はプールを論理削除します。現在プールに接続中のマシンには影響しません。

ワーカーを再びスケールアップするタイミングは、List Pools と 保留中のリクエスト を使用して判断してください。

プール名

GPU マシン、ステージング環境のワーカー群、またはチーム専用のビルドマシンなど、特定のサブセットにセッションをルーティングしたい場合は、プール内のワーカーを名前でグループ化します。

名前は --pool に渡します。

agent worker --pool my-pool start

名前を省略すると、ワーカーは default プールに参加します。boolean の --pool と別個の --pool-name のみをサポートしていた古い CLI バージョンも引き続き動作します。--pool-name は --pool <name> の非推奨エイリアスです。

オーケストレーターが設定を注入する場合は、環境からプール名を設定します。

export CURSOR_WORKER_POOL_NAME=my-poolagent worker --pool start

複数回利用ワーカー (--pool なしで起動したワーカー) はプールに属しません。

Cloud Agents ダッシュボードで、セッション開始時または自動化の編集時に、ワーカーセレクターからプールを選択します。Slack、GitHub、または Linear のトリガーに pool=<name> を含めることもできます。セッションは、そのプール名で登録されているワーカーにのみルーティングされます。

プールエージェントのトリガー

チームの共有ワーカー群上で Cloud Agent を実行したい場合は、プールトリガーを使用します。プールワーカーは、一元管理されたキャパシティ、オートスケーリング、CI のようなランナー、リポジトリ単位のインフラストラクチャに適したターゲットです。

チーム管理者は、Cloud Agents ダッシュボード の Self-Hosted セクションからセルフホスト型のルーティングを管理します。Allow Self-Hosted Machines では、ユーザーがリクエストごとに opt-in できます。opt-in しない場合、実行には Cherri Code の管理インフラストラクチャが使用されます。Require Self-Hosted Machines では、Cloud Agent の実行がセルフホスト型ワーカーにルーティングされます。

Cherri Code がプールエージェントを開始すると、ラベル を使ってワーカーを照合します。リポジトリ向けのプールリクエストには repo=<owner/repo> ラベル が含まれます。リポジトリを指定しない 任意のリポジトリ対応プール へのリクエストでは省略されます。名前付きプールへのリクエストには、pool=<name> も含まれます。

プールワーカーが処理するもの:

• リクエストが worker= または machine= で特定のマイマシンワーカーをターゲットにしていない限り、Require Self-Hosted Machines の対象となる実行
• self_hosted=true またはその短縮形 sh=1 を含むリクエスト
• pool=<name> を含むリクエスト。これにより、その名前付きプールも選択されます
• repo=<owner/repo> など、トリガー surface からの リポジトリ selection を含むセルフホスト型リクエスト (対応している場合)

repo= は実行対象の リポジトリ を選択します。チームプール の実行では、その リポジトリ が repo=<owner/repo> ワーカー ラベル になります。個人用マシンはターゲットになりません。

連携からプールエージェントを開始するには、次のオプションを使用します:

• Slack: self_hosted=true、sh=1、または pool=<name> を付けて @Cherri Code をメンションします。チーム管理者は @Cherri Code pool set <name> で チームのデフォルトプール を設定でき、メンバーはメンションごとにオプションを指定せずにそのプールで実行できます。@Cherri Code pool set <name> channel で設定した チャネルのデフォルトプール は、そのチャネル内ではチームのデフォルトプールに優先します。明示的な pool=、worker=、machine=、self_hosted=false はどちらのデフォルトも上書きし、任意のリポジトリ用のデフォルトプールでは、リポジトリが解決されていなくても Slack から起動できます。
• GitHub: issue、プルリクエスト、または review comment に @cursoragent self_hosted=true ...、@cursoragent sh=1 ...、または @cursoragent pool=<name> ... とコメントします。
• Linear: コメントで self_hosted=true、sh=1、pool=<name>、または [pool=<name>] を付けて @Cherri Code をメンションします。Cherri Code はこれらのオプションを issue の説明ではなく、そのコメントから読み取ります。親ラベルが pool、子ラベルがプール名である issue ラベルまたはプロジェクトラベルも使用できます。issue を Cherri Code に 委任する 場合は読み取るコメントがないため、プールを選択できるのはラベルだけです。コメント内の pool= はプールラベルより優先され、self_hosted=false がある場合はプールラベルが無視されます。

各オプションは key=value の形式で記述します。self_hosted とその短縮形 sh は、opt-in には true、t、1、opt-out には false、f、0 を受け付けます。それ以外の値は、テキストとしてプロンプトに残ります。これには、値のない self_hosted、selfhosted、sh や、sh=/bin/bash などのその他の値も含まれます。Slack、GitHub、Linear はいずれもコードブロック内のこれらのオプションを無視するため、貼り付けたコードによってエージェントの実行場所が変わることはありません。

ポリシー処理は、リクエストの開始元によって異なります:

• Slack は、Allow Self-Hosted Machines がオフのとき、セルフホスト型への opt-in を拒否し、Slack 上で返信します。Require Self-Hosted Machines がオンの場合、すべての Slack メンションがセルフホスト型で実行されます。
• GitHub では、リポジトリの OWNER と COLLABORATOR ユーザーが実行をセルフホスト型ワーカーにルーティングできます。その他のコメント投稿者は、opt-in した場合は管理インフラストラクチャ上で実行され、Require Self-Hosted Machines がオンの場合はスキップされます。これにより、外部コントリビューターがコメントを残せる public リポジトリを保護できます。
• Linear は、Allow Self-Hosted Machines がオフのときに明示的なセルフホスト型リクエストを拒否します。issue には、管理者にセルフホスト型ワーカーを有効にするか、Cherri Code の管理インフラストラクチャで実行するためにヒントを削除するよう求めるエージェントのアクティビティ エラーが表示されます。

自分のマシンの 1 つを名前でターゲットにするには、worker= または machine= と一緒に マイマシン を使用します。

Cloud Agent API では、usePrivateWorker フィールドと labels フィールドに同じ resolver を使用します。エンドポイント の詳細は Cloud Agent API docs を参照してください。

Hooks

セルフホスト型マシンのワーカーは、Cloud Agent セッション中に command-based フック を実行します。設定は、ワーカーが担当するワークスペースから読み込まれます。

• Project hooks. .cursor/hooks.json と、そこから参照されるスクリプトを、ワーカーが使用するリポジトリまたはワークスペースのディレクトリに commit してください。具体的には、Git チェックアウト、--worker-dir のルート、または任意のリポジトリ対応プールに渡すディレクトリです。
• Team and enterprise-managed hooks. エンタープライズでは、ワーカーは web ダッシュボード で設定されたフックも実行します。

Hooks のリファレンスでは、スキーマ、イベント、例を説明しています。Cloud agent support には、Cloud Agent ループが実行するイベントの一覧があります。

これらのツール実行ワーカーにも適用される Cloud Agent の制限は次のとおりです。

• Command-based hooks only. Prompt-based hooks は実行されません。
• No IDE-only hooks. Tab hooks (beforeTabFileRead、afterTabFileEdit) と workspaceOpen はワーカーでは実行されません。

sessionStart と sessionEnd はセルフホスト型マシンのワーカーで実行されます。Cloud Agent セッションがワーカーを claim したときと、その claim が解放されたときに発火します。Cherri Code 管理の Cloud Agents では、これらのフックはスキップされます。

Kubernetes やその他のオーケストレーション基盤上のワーカーも、これと同じフックのモデルを使用します。

ラベル

ラベルはワーカーを表すキーと値のペアです。Cloud Agent セッションを適切なプールにルーティングする方法を制御します。

agent worker \  --pool \  --label team=backend \  --label env=production \  start

repo と pool のラベルは予約済みです。repo は、存在する場合にワーカーディレクトリの Git リモートから取得されます。pool は --pool で設定されます。どちらも手動で設定しないでください。

MCP サーバー

セルフホストワーカー上の MCP サーバーは、トランスポートの種類ごとにルーティングされます。

MCP サーバーがプライベートネットワークのエンドポイントにアクセスする必要がある場合は、Command (stdio) トランスポートを使用してください。プロセスはワーカー上で直接実行され、そのネットワークを共有します。HTTP ベースの MCP サーバーでは、Cherri Code がバックエンドから接続を管理し、OAuth とセッションキャッシュを処理します。

アーティファクト

アーティファクトの挙動は、セルフホストワーカーでも Cherri Code-hosted エージェントでも同じです。エージェントがワーカー内でアーティファクトを生成し、ワーカーがそれを HTTPS 経由で Cherri Code-managed ストレージにアップロードします。その後の処理 (PR の埋め込み、ダッシュボードプレビュー、通知の添付ファイル) はすべて Cherri Code のバックエンドで行われ、ワーカーがどこで実行されているかには依存しません。

アーティファクトはデフォルトで有効です。UI でどのように表示されるかについては、機能を参照してください。

アーティファクトのアップロードを無効にするには、cloud-agent-artifacts.s3.us-east-1.amazonaws.com へのアウトバウンドトラフィックをブロックしてください。エージェントセッションは引き続き動作しますが、セッション中に生成されたアーティファクトはアップロードに失敗します。

ネットワーク

ワーカーでは、以下へのアウトバウンド HTTPS アクセスが必要です。

• エージェント セッション用の api2.cursor.sh と api2direct.cursor.sh
• CLI の更新、および macOS での初回の Cherri Code Computer Use インストール用の downloads.cursor.com
• アーティファクト をアップロードするための cloud-agent-artifacts.s3.us-east-1.amazonaws.com

ファイアウォールでワイルドカードしか使えない場合、*.s3.us-east-1.amazonaws.com でアーティファクトのホストはカバーできますが、同時にそのリージョン内の他のすべてのバケットも開放されます。ファイアウォールが対応している場合は、ホストを正確に指定するルールを優先してください。

インバウンド ポート、パブリック IP、VPN トンネルはいずれも不要です。プロキシを使用する場合は、ワーカー環境で HTTPS_PROXY または https_proxy を設定してください。

障害時の挙動

前提条件 セクションでは、エージェント実行中にワーカーが必要とする、より広範なホスト群 (Git ホスト、パッケージ レジストリ、内部 API) について説明します。

Kubernetes にデプロイ

スケジューリング、ヘルスチェック、Pod のライフサイクルをプラットフォーム側に任せたい場合は、Kubernetes 上で プールワーカー を実行します。まずは anysphere/k8s-workers から始めてください。これは、クラスター内で ワーカーコントローラー を --spawn 付きで実行する Helm のサンプルです。spawn フックは 割り当て済み リクエストごとに 1 つのワーカー Pod を作成し、--warm-idle を指定した場合はコントローラーがウォームなアイドル Pod を維持します。CRD は不要です。

その他のホストでも仕組みは同じです。Cherri Code CLI をインストールでき、アウトバウンド HTTPS で Cherri Code に接続できる VM、コンテナ、ベアメタルマシンであれば、systemd、Docker、または独自のプロセスマネージャー上で プールワーカー を実行できます。AWS Lambda、Cloudflare、Namespace、Modal、Daytona、E2B、Vercel、Tensorlake、Coder、SuperServe を対象としたパートナーガイドやリファレンステンプレートについては、Integrations を参照してください。

ワーカーコントローラー

agent worker controller は --spawn フックからワーカーを起動します。フックは、k8s-workers テンプレート のように、プロセスをフォークしたり、コンテナを起動したり、Kubernetes Pod を作成したりできます。--warm-idle はウォーム容量向けの経路で、コントローラーは Deployment や HPA にパッチを適用する代わりに、不足しているアイドルワーカーごとにフックを 1 回実行します。WorkerDeployment.spec.readyReplicas は非推奨の Kubernetes operator に属するもので、この制御が必要なのは既にそれを稼働させているクラスターだけです。

--spawn <path> は必須です。フックは、クレーム成功後に 1 回、または不足しているウォームワーカーごとに 1 回実行されます。フックの環境には CURSOR_API_KEY (--session-token を使用する場合は代わりに CURSOR_AUTH_TOKEN)、CURSOR_API_URL、CURSOR_API_ENDPOINT、CURSOR_AGENT_WORKER_ID、およびリクエストのフィールドが含まれます。認証には、サービスアカウント のキーを --api-key または CURSOR_API_KEY で指定します。キーによってチームが決まります。セッションログインは使用しません。

spawn フックには、必要な情報がすべて環境変数として渡されます:

spawn フックは、同じ ワーカー id でワーカーを起動する必要があります:

#!/usr/bin/env bashset -euo pipefailagent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start

ワーカー CLI は CURSOR_AGENT_WORKER_ID を環境変数からも読み取るため、コンテナを起動する spawn フックから代わりにこれらの変数を渡すこともできます:

#!/usr/bin/env bashset -euo pipefaildocker run -d \  -e CURSOR_API_KEY \  -e CURSOR_AGENT_WORKER_ID \  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \  your-worker-image \  agent worker --pool start

Claim-then-spawn

デフォルトのモードです。コントローラーは保留中のリクエストを一覧表示し、GET /v0/private-workers/pending-requests/stream を監視して各リクエストを クレーム し、クレーム ごとに 1 回ずつ --spawn を exec します。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --pool default

ウォームプール

--warm-idle <count> は、未割り当てのワーカーを事前に spawn することで、各 --pool に <count> 個のアイドルワーカーを接続した状態で維持します。クレーム は一切呼び出しません。Cherri Code は、キューに入ったエージェントをこれらのウォームワーカーに割り当てます。

コントローラーは 60 秒ごとに GET /v0/private-workers/pools に対して reconcile を実行します。保留中リクエストの SSE ストリームは、backfill を高速化するだけのものです。

ウォームモードには --pool が必要で、--all-pools とは併用できません。ウォームコントローラーはプールごとに 1 つだけ実行してください。サーバー側に spawn のリースがないため、複数のコントローラーが同時に動作すると一時的に spawn が過剰になることがあります。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --warm-idle 5

セッショントークン

デフォルトでは、spawn フックが起動するすべてのマシンがサービスアカウントの API キーを保持します。--session-token を指定すると、コントローラーはクレームごとにセッショントークンを要求し、API キーの代わりにそのトークンをフックに渡します。これにより、キーはコントローラー上にのみ保持されます。

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --session-token

フックには、CURSOR_API_KEY の代わりに CURSOR_AUTH_TOKEN と CURSOR_AUTH_TOKEN_EXPIRES_AT が渡されます。トークンをファイルに書き込み、--auth-token-file を指定してワーカーを起動します：

#!/usr/bin/env bashset -euo pipefailprintf '%s' "$CURSOR_AUTH_TOKEN" > /run/cursor/tokenagent worker --pool "$CURSOR_POOL" --auth-token-file /run/cursor/token start

セッショントークンには次の特徴があります。

• 1 つのクレームにのみ対応します。 接続できるのは割り当て済みのワーカー ID のみで、ワーカーが呼び出さないエンドポイントでは、Cherri Code はすべてこのトークンを拒否します。
• クレームとともに失効します。 クレームが解放されたとき、またはトークンを発行したサービスアカウントキーが削除されたか期限切れになったときに使用できなくなります。CURSOR_AUTH_TOKEN_EXPIRES_AT の 7 日間の有効期限は、あくまで最終的な安全策です。
• 再発行できます。 ハイバネーションから復帰したマシンや、トークンの有効期限を超えて続く実行など、すでに保持しているクレーム用のトークンが必要なワーカーは、Create A Session Token から取得できます。ハイバネーション中のマシンを復帰させる際は、コントローラーがこれを自動で行います。新しいトークンは同じファイルに書き込んでください。ワーカーは再接続時にファイルを読み直します。

ウォームワーカーはクレームが存在する前に起動するため、--warm-idle を指定したコントローラーでは、引き続きフックに API キーを渡します。Cherri Code がセッショントークンを拒否すると、ワーカーは終了し、トークンの有効期限やクレームの終了など、その理由を出力します。

独自のコントローラーを作る場合は、Cloud Agents API を使用してください。

セッションのライフサイクル

worker がリクエストにマッチすると、Cherri Code はエージェントのツール呼び出しをすべてそのマシンへ直接転送します。この接続にはアイドルタイムアウトがあり、デフォルトは 1 時間です。必要に応じて設定してください:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (環境変数 CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) は、セッション終了後にワーカーが後続メッセージを待って接続を維持する秒数です。後続メッセージが届くとタイマーはリセットされます。タイムアウトが発生すると CLI は終了コード 0 で終了するため、スーパーバイザーがマシンをリサイクルできます。アイドル時の解放を無効にするには 0 を指定します。クレームの解放 は別の API で、そのマシンをエージェント向けに優先することをやめるだけで、ワーカー CLI を終了させることはありません。

ワーカーがタイムアウトすると、Cherri Code はそのワーカーを解放済みとしてマークします。マシンはリセットしてプールに再び加わることができます。マシンとの接続が切れたチャットをユーザーが再開すると、そのチャットはプール内の新しいマシンに接続されます。元のマシンのワークスペース状態は、プールが hibernation を使用していない限り引き継がれません。

ハイバネーション

プール内のマシンは、エージェントがアイドル状態の間もオンラインであり続ける必要はありません。セッション終了後、ワーカーはアイドルタイムアウトが発火するまでフォローアップを待ちますが、ターンの合間もすべてのマシンを起動したままにしておくとコストがかさみます。

ここでのトレードオフはワークスペースの局所性です。ハイバネーションがない場合、マシンの解放後に届いたフォローアップはプールから再取得されます。エージェントは新しいマシンに割り当てられ、すでに用意できていたワークスペースの再構築に最初の数分を費やすことになりかねません。ハイバネーションを使えば、マシンはワークスペースを保ったまま復帰し、フォローアップはエージェントが中断した地点から再開されます。

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "my-pool",    "workerReadyTimeoutSeconds": 900  }'

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"agent worker --pool my-pool start

独自のコントローラーを作る

組み込みのコントローラーはほとんどのセットアップに対応します。独自のスケジューリング、クォータ、マシン配置など、カスタムのロジックが必要な場合は、Cloud Agents API を使ってコントローラーを作ります。コントローラーが行うことは 3 つです。リクエストキューを監視する、リクエストを クレーム する、そのリクエスト用のワーカーを起動する、です。同じエンドポイントは、Kubernetes 以外での使用率の監視やオートスケーリングにも利用できます。

プールのサービスアカウントの API キーを使用し、Basic 認証または Bearer トークンで認証してください。他の種類の API キーでは、プールのプールワーカーのキャパシティを管理できません。

リクエストキューを監視する

まずキューを一度一覧取得して保留中のリクエストの状態を把握し、その後は Server-Sent Events (SSE) で変更をリアルタイムに追跡します。

まず GET /v0/private-workers/pending-requests を呼び出します。特定の プール のみを監視する場合は ?pool=<name> を追加します。すべてのページを取得しきったうえで、レスポンスの streamCursor を保持しておきます:

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \  -u "$CURSOR_API_KEY:"

次に、GET /v0/private-workers/pending-requests/stream でイベントストリームを開き、その streamCursor と同じフィルターを渡します。イベントが届くたびにビューを最新の状態に保ってください。created および claimed_offline イベントを受け取ったら request を追加し、claimed または expired を受け取ったら request を削除します。

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

カーソルは、それを発行したリストの5分後に期限切れになります。ストリームが 410 Gone を返したら、リストを取得し直し、新しい streamCursor からストリームを開き直してください。さらに望ましいのは、410 を待たずに、5分ごとに多少のジッターを加えてリストを再取得することです。

ビューに表示されるリクエスト数は、プールのキューの深さを表します。これが増えてきたらワーカーを追加してください。イベントはあくまでヒントとして扱い、リストを信頼できる情報源としてください。イベント配信はベストエフォートであり、リストを取得し直すたびにずれが補正されます。配信保証とカーソルのルールの詳細については、Watch Pending Pool Requests を参照してください。

ワーカーを一覧表示

curl --request GET \  --url "https://api.cursor.com/v0/private-workers?status=idle&scope=team_pool&limit=50" \  -u "$CURSOR_API_KEY:"

ワーカーには name、isInUse、接続メタデータ、リポジトリ フィールドが含まれます (任意のリポジトリ用ワーカーの場合、repoOwner/repoName は空文字列になります) 。レスポンス全体については API リファレンス を参照してください。

プールの一覧取得

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pools?scope=team_pool" \  -u "$CURSOR_API_KEY:"

永続プールを connectedWorkerCount、inUseWorkerCount、isStale、および任意指定のリポジトリフィールドとともに返します。任意のリポジトリ対応プールでは、リポジトリフィールドは省略されます。プールごとの接続中・使用中の数を取得するには、これを使用してください。以下のチーム全体のワーカーサマリーは、プール単位の需要を把握する代わりにはなりません。

ワーカーの概要を取得

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

ユーザーとチームの接続数と使用中数を返します。Get Worker Summary を参照してください。キューの深さが増したときの対応規模の調整や、使用率が高い場合のスケーリングのトリガーに使用します:

const summary = await response.json();const team = summary.teamSummary;if (team && team.totalConnected > 0) {  const utilization = team.inUse / team.totalConnected;  if (utilization >= 0.9) {    // スケールアップ: 追加のワーカーをプロビジョニングする  }}

IDを指定してワーカーを取得

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

保留中のリクエストをクレームする

エフェメラルなコントローラーは、ワーカーを起動する前にキュー内のリクエストを予約できます。

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

次に、同じ ID (CURSOR_AGENT_WORKER_ID=pw_123) でワーカーを起動します。Claim A Pending Request を参照してください。

サービスアカウントキーをワーカー側に置かないようにするには、本文に "sessionToken": true を追加します。その場合、レスポンスにはさらに、token にセッショントークンが、expiresAt にその有効期限が含まれます。トークンをファイルに書き込み、キーの代わりに --auth-token-file を指定してワーカーを起動してください。

セッショントークンを発行する

チームがすでに保持しているクレームに対して、新しいセッショントークンを取得します。ハイバネート状態のマシンを復帰させる場合などに使用します。

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/tokens" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Create A Session Token を参照してください。

クレーム を解放する

エージェントを self-hosted worker に紐付けている クレーム を解除します。これにより、Cherri Code はそのエージェントに対して当該マシンを優先しなくなります。

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

有効な クレーム が存在する状態で 2 つ目の クレーム を行うと拒否されます。先に release してから、新しい workerId を クレーム してください。Release A Claim を参照してください。

監視

--management-addr を指定してワーカーを起動すると、管理サーバーは GET /metrics、GET /healthz、GET /readyz を提供します。

agent worker --pool --management-addr ":8080" start

ワーカーからスクレイプできるメトリクス:

curl http://localhost:8080/metrics

利用可能なメトリクス

ゲージ

カウンター

セッション終了の理由

cursor_self_hosted_worker_session_ends_total カウンターには、次のいずれかの値を持つ reason ラベルが含まれます。

セキュリティ

データフロー。 お使いのネットワークの外に出るのは 2 つだけです。1 つは推論時にモデルが読み取るファイルチャンク、もう 1 つはワーカーが PR やダッシュボードに表示できるよう Cherri Code 管理のストレージにアップロードする Cloud Agent のアーティファクト (スクリーンショット、動画、ログ参照) です。リポジトリ、ビルドキャッシュ、シークレットはお使いのマシン上にとどまります。

アウトバウンドのみ。 ワーカーは HTTPS 経由のアウトバウンド接続を使用します。インバウンドポートの開放やファイアウォールの変更は不要です。

プライバシーモード。 セルフホスト型 Cloud Agents は Cherri Code のプライバシーモード設定に従います。プライバシーモードが有効な場合、コードが学習に使用されることはありません。

分離。 各エージェントセッションには専用のワーカーが割り当てられます。セッションがワーカー間で共有されることはありません。

認証。 プールワーカーはサービスアカウントの API キー、または 1 回のクレームにのみ有効なセッショントークンで認証します。セッショントークンを使えば、キーがワーカーに渡ることはありません。その他の種類の API キーは受け付けられません。

ダッシュボードの表示。 チーム管理者は接続されているすべてのワーカーを確認できます。チームメンバーに表示されるのは、自分に割り当てられたワーカーのみです。

CLI リファレンス

agent worker [options] start

よくある質問

次のステップ

• anysphere/k8s-workers: agent worker controller --spawn をベースにした Kubernetes template。claim-then-spawn と --warm-idle モードに対応。
• Integrations: 他プラットフォーム向けの partner guide と リファレンス templates。
• Kubernetes operator (非推奨): すでに WorkerDeployment operator を稼働させている cluster 向けのリファレンス。
• Computer use: ワーカー 上のデスクトップとブラウザをエージェントに操作させます。
• API リファレンス: ワーカー、プール、保留中のリクエストキュー、ワーカー token 向けの エンドポイント。