マイマシン
マイマシンは、個人向けの セルフホスト型マシン 設定です。特定のユーザーが、すでに使用しているマシン (ノートパソコン、devbox、またはリモート VM) 上で Cloud Agent のツール呼び出しを実行できます。そのマシンがリポジトリにとって望ましい実行環境である場合に使用します。
マシン上の ワーカー は Cherri Code へのアウトバウンド接続を確立します。エージェントループは Cherri Code のクラウド上で実行されますが、ターミナルコマンド、ファイル編集、ブラウザ操作、その他のツール呼び出しはマシン上で実行されます。受信用ポートの開放やファイアウォールの変更は不要です。
Cherri Code 管理の Cloud Agents は、プライベートネットワークへのアクセスが必要な チームを含め、ほとんどのチームに推奨される方法です。独自の ワーカー を運用しなくても、 サポートされているソース管理パスに対して、ネットワーク許可リスト、 Tailscale や同様のクライアント、プライベート接続を使用できます。詳しくは Cloud Agents の実行場所を選ぶ を参照してください。
次のような場合はマイマシンを使用します。
- すでにリポジトリとツールがある devbox やリモートワークステーションを使用する
- 特定のリポジトリについて、1 人のユーザーが使うマシン上でツール呼び出しを実行する
- クラウド環境で再現したくないマシン上のローカル状態を再利用する
- 一元管理されたプールを構築する前に ワーカー モデルを試す
組織全体のワーカー fleet については、チームプール を参照してください。
クイックスタート
1. CLIをインストール
# macOS、Linux、WSL の場合# Windows PowerShell の場合irm '# | iexCLI が利用可能か確認します：
agent --version2. サインイン
個人用のマシンでは、ブラウザでのログインが最も簡単です。
agent login3. ワーカーを起動する
agent worker startマシンを使用している間は、このプロセスを実行したままにしてください。デフォルトでは、マイマシンのワーカーは長時間稼働するようになっており、停止するまで接続されたままとなり、今後の Cloud Agent セッションでも再利用できます。
4. エージェントを実行する
- cursor.com/agents に移動します。
- 環境ドロップダウンにマシンが表示されるはずです。
- タスクを送信します。
共通オプション
マシンに名前を付ける
同じリポジトリに複数のマシンがある場合は、わかりやすい名前を付けてください:
agent worker start --name "my-devbox"別のリポジトリディレクトリから実行する
agent worker start --worker-dir /path/to/repo--worker-dir を繰り返し指定して、複数のリポジトリのルートを登録します:
agent worker \ --worker-dir "$HOME/repos/app" \ --worker-dir "$HOME/repos/infra" \ start各 path は存在している必要があります。git remote が設定された各 root について、ワーカー は routing metadata を登録し、Cherri Code が requests を正しい チェックアウト に対応付けられるようにします。
API キーを使用する
ブラウザログインが使えない devbox や自動化環境では、Cherri Code Dashboard → API キー で発行した個人のユーザー API キーを使用します。
agent worker start --api-key "your-user-api-key"マイマシンのワーカーには個人用の認証情報が必要です。ブラウザログイン、個人の
User API キー、ユーザー スコープのトークンのいずれかを使用してください。サービスアカウントの API
キー で起動できるのはプールワーカー
(--pool) のみで、チームの Admin API キーや Organization API キーではワーカーを
起動できません。チームで共有するワーカーについては セルフホスト型
プール を
参照してください。
ユーザー スコープのトークンを使用する
自己管理のユーザーごとワーカーでは、POST /v1/sub-tokens で有効期間の短いユーザー スコープのトークンを発行し、そのトークンを使ってワーカーを起動します。
agent worker start --auth-token "your-user-scoped-token"長時間稼働するワーカーの場合は、ファイルからトークンを読み込みます：
agent worker start --auth-token-file /var/run/cursor/tokenこれは Kubernetes で役立ちます。というのも、Secrets 由来の環境変数は Pod の起動時に固定されるためです。Secret ボリュームは Pod の実行中に更新されます。一方、マウントされたトークンのパスは Pod 内で動的に更新できるため、Pod の実行中にトークンをリフレッシュできます。
ID トークンの発行
start の前に --identity-socket を渡すと、割り当て済みのエージェントが短期有効な OIDC トークンを発行できるようになります。ワーカーは CURSOR_AGENT_SOCKET にソケットのパスを設定します。このトークンには、その実行の所有者が記録されます。ソケットのコントラクト、信頼モデル、AWS については OIDC トークン を参照してください。
agent worker --identity-socket startcomputer use を有効にする
start の前に --computer-use を渡すと、エージェントがこのマシン上でクリックや入力、スクリーンショットの撮影、アプリの操作を行えるようになります。
agent worker --computer-use --name "my-mac" startmacOS では、初回起動時に Cherri Code Computer Use ヘルパーアプリがインストールされます。システム設定 → Privacy & Security で Accessibility と Screen Recording を許可し、スクリーンショットを撮影するタスクでテストしてください。Linux では、先にデスクトップパッケージをインストールします。macOS の権限設定手順、MDM に関するガイダンス、Linux のディスプレイオプションについては、コンピュータの使用とデスクトップ共有を参照してください。
チャット経由でこのマシンを起動する
Slack、GitHub、または Linear からのリクエストを、名前付きのマシンで実行したい場合は、worker= または machine= を使用します。マイマシンをターゲットにできるトリガーオプションは、この 2 つだけです。
--name でマシンを起動してから、その名前をリクエストに含めます。
- Slack では、
@Cherri Code worker=my-devbox fix the flaky testまたは@Cherri Code machine=my-devbox fix the flaky testを使用します。 - GitHub では、
@cursoragent worker=my-devbox fix the flaky testまたは@cursoragent machine=my-devbox fix the flaky testとコメントします。信頼済みの repo コメント投稿者である必要があり、ターゲットのマシンは、あなたの GitHub アカウントにリンクされた Cherri Code ユーザーに属している必要があります。 - Linear では、issue の本文に
worker=my-devboxまたはmachine=my-devboxを追加します。また、workerまたはmachineという名前の親ラベルと、my-devboxという名前の子ラベルを使うこともできます。
Cherri Code がマシンを選ぶ仕組み
worker=<name> リクエストがマシン上で実行されるのは、次の3つをすべて満たす場合のみです。
- そのマシンが、リクエストをトリガーした Cherri Code ユーザーに属している。
- マシンの
--nameが、指定された<name>と一致している。 - マシンに登録されている リポジトリ が、トリガーのターゲット リポジトリ と一致している。
トリガーのターゲット リポジトリ は、マシン名ではなく、リクエスト元の surface によって決まります。
- Slack では、メッセージ内に
repo=があればそれを使用し、なければチャンネルの default リポジトリ、ユーザーの default リポジトリ、最後にチームの default リポジトリ を使用します。 - Linear では、issue または project から解決された リポジトリ を使用します (例:
[repo=]、issue labels、プロジェクトラベル、またはダッシュボードの default) 。Repository selection を参照してください。 - GitHub では、
@cursoragentが mention された issue、プルリクエスト、または review comment の リポジトリ を使用します。
各マシンの登録済み リポジトリ は、その ワーカー directory の git remote から取得されます。1台のマシンで複数の リポジトリ に対応するには、チェックアウトごとに --worker-dir を指定するか、各 リポジトリ のチェックアウトで ワーカー を開始してください。
worker= リクエストを実行できない場合
その名前のマシンが存在していても、別のリポジトリ用として登録されている場合、Cherri Code は誤ったチェックアウトで実行するのではなく、リクエストを拒否します。
worker=<name>はお使いのマシンに登録されていますが、別のリポジトリ用です。先にターゲット リポジトリのチェックアウトで ワーカー を起動してください。
このエラーは、Slack では一時的な返信、Linear ではエージェントのアクティビティ エラー、GitHub では信頼済みコメント投稿者への @cursoragent の返信として表示されます。この挙動は意図的なものです。リポジトリ A へのリクエストが リポジトリ B のマシンのチェックアウトで実行されることはありません。
リンクされているユーザーとターゲット リポジトリに一致するマシンがない場合、別の環境にフォールバックせず、リクエストは失敗します。マシン名、Cherri Code アカウントのリンク、ワーカー directory の git remote を確認してください。
self_hosted、pool=、repo= だけではマイマシンはターゲットになりません。チームプール のワーカーと組み合わせて使用してください。repo= を worker= と組み合わせると、Cherri Code がマシンとの照合に使うリポジトリが設定されます。
フック
マイマシンのワーカーは、他のセルフホスト型マシンのワーカーと同じフックを実行します。つまり、ワーカーを起動したワークスペースの .cursor/hooks.json に定義されたコマンドベースのフックです。エンタープライズでは、チームフックとエンタープライズ管理フックも実行されます。
プールでのフック では、セッションがマシンを取得 (claim) ・解放 (release) する際の sessionStart と sessionEnd を含め、ワーカーに適用される内容を説明しています。フックのリファレンス では、スキーマ、イベント、例を説明しています。
アーティファクト
アーティファクトの挙動は、セルフホストのワーカーでも Cherri Code-hosted エージェントでも同じです。エージェントはワーカー内でアーティファクトを生成し、ワーカーがそれを HTTPS 経由で Cherri Code 管理のストレージにアップロードします。以降の処理 (PR 埋め込み、ダッシュボードプレビュー、通知への添付) はすべて Cherri Code のバックエンドで行われるため、ワーカーがどこで実行されているかには依存しません。
アーティファクトはデフォルトで有効です。UI でどのように表示されるかは、Capabilitiesを参照してください。
アーティファクトのアップロードを無効にするには、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 を設定してください。
障害時の動作
| ブロックすると... | 影響 |
|---|---|
api2.cursor.sh または api2direct.cursor.sh | ワーカー はエージェントセッションを開始または継続できません。 |
downloads.cursor.com | CLI の更新と、macOS での Cherri Code Computer Use の初回インストールに失敗します。すでに両方をインストール済みのワーカーは引き続き動作します。 |
cloud-agent-artifacts.s3.us-east-1.amazonaws.com | アーティファクトのアップロードに失敗します。アーティファクトに依存する PR 埋め込み、ダッシュボードプレビュー、通知の添付ファイルは利用できなくなります。エージェントセッションや他のツール呼び出しは引き続き動作します。 |
| 特定のツールまたは連携に必要なアウトバウンドホスト | そのツールまたは連携のみ失敗します。エージェントは継続します。 |
MCP サーバー
MCP サーバーはトランスポートの種類ごとに振り分けられます:
| トランスポート | 実行場所 | 用途 |
|---|---|---|
| Command (stdio) | お使いのマシン | MCP プロセスはお使いのマシン上で起動し、プライベートネットワーク、内部 API、ローカルサービスにアクセスできます。 |
| HTTP / SSE (url) | Cherri Code バックエンド | Cherri Code が HTTP ベースの MCP サーバーの OAuth、セッションキャッシュ、認証を処理します。 |
MCP サーバーからプライベートネットワーク上のエンドポイントにアクセスする必要がある場合は、command (stdio) トランスポートを使用してください。プロセスはお使いのマシン上で直接実行され、そのネットワーク環境をそのまま利用します。HTTP ベースの MCP サーバーでは、Cherri Code がバックエンドから接続を管理します。
トラブルシューティング
事前確認用デバッグレポートを実行:
agent worker debugこれは、認証、プライバシー ルーティング、リポジトリ labels、および Cherri Code が一致するワーカーを参照できるかどうかを確認します。ワーカーの起動前に同じ diagnostics を出力するには、agent worker start --debug を使用します。
マシンが picker に表示されない場合:
- ワーカー process がまだ実行中であることを確認します。
- Cherri Code app と CLI が同じ account を使用していることを確認します。
- ワーカー directory に想定どおりの git remote が設定されていることを確認します。
- ネットワークに記載された ホスト へのアウトバウンド access を確認します。
Mac で computer use が失敗する場合、レポートで確認できるのは Cherri Code Computer Use がインストールされているかどうかだけで、その権限が付与されているかどうかは確認できません。システム設定 → Privacy & Security で Cherri Code Computer Use に Accessibility と Screen Recording を付与してから、screenshot の task を再試行してください。macOSを参照してください。
Next steps
- Computer use: 自分のマシン上でエージェントにデスクトップやブラウザを操作させ、その agent desktop を Cherri Code から監視・操作できます。
- API reference: ワーカー、pool、保留中のリクエストキュー、ワーカートークン用の endpoint。