> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックスで Cursor を実行する

> CoreWeave サンドボックスで Cursor CLI をインタラクティブに実行したり、コーディングタスクを自動化したりします。

CoreWeave サンドボックス内のリポジトリを対象に、Cursor のコマンドラインインターフェース (CLI) を実行します。
対話的に作業する場合はターミナルをアタッチし、それ以外の場合は Sandboxes ソフトウェア開発キット (SDK) からプロンプトを実行して結果を取得します。CLI プロセス、
ワークスペース、コマンドはすべてサンドボックス内で実行されます。モデルへのリクエストは Cursor に送信されます。

Cursor は [Self-Hosted Machines](https://cursor.com/docs/cloud-agent/self-hosted) もサポートしています。
この構成では、Cursor のクラウドがエージェントループを実行し、別のワーカーがツール呼び出しを処理します。

<h2 id="prerequisites">
  前提条件
</h2>

開始する前に、以下を準備してください。

* `cws-agent` パスに対する `SANDBOX_USER` action が付与された [CoreWeave API アクセストークン](/ja/products/sandboxes/get-started#coreweave-api-access-token)。SDK では、シークレット注入に Forge APIキーも使用できます。詳しくは、[Cursor キーの指定方法を選択する](#choose-how-to-supply-the-cursor-key)を参照してください。

* [Cursor ユーザー APIキー](https://cursor.com/docs/cli/reference/authentication#api-key-authentication)
  と、Cursor CLI がサポートするモデルへのアクセス権。

* 公開リポジトリの URL。非公開リポジトリを使用する場合は、サンドボックス内に Git の認証情報が
  必要です。

* Cursor、そのダウンロードホスト、および使用する Git ホストへのアウトバウンド接続。

ローカルのターミナルで、CoreWeave API アクセストークンを設定します。

```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
```

Cursor はサンドボックス内で `CURSOR_API_KEY` を読み取ります。Cursor は
プロンプト、ファイルの内容、ツールの出力を Cursor のサービスに送信することがあります。タスクに適したリポジトリと
認証情報を使用してください。

<h2 id="run-cursor-cli-with-cws-agent">
  cws-agent で Cursor CLI を実行する
</h2>

`cws-agent` を使用すると、サンドボックスの作成、Cursor のインストール、ターミナルのアタッチをまとめて行えます。
対話型のアタッチには、macOS、Linux、
または Windows Subsystem for Linux (WSL) 上の対話型ターミナル (TTY) が必要です。Windows ネイティブのターミナルはサポートされていません。

Cursor のキーをローカル環境でエクスポートしてください。`cws-agent` がこのキーをサンドボックスの
環境に転送します:

```bash theme={"system"}
export CURSOR_API_KEY="[CURSOR-API-KEY]"
```

1. [`cws-agent` のインストール手順](https://github.com/coreweave/cws-agent#install)に従います。

2. `[SANDBOX-NAME]` を、英小文字、数字、ハイフンからなる 1～40 文字の
   セッション名に置き換えます。先頭は英小文字または数字にしてください。
   `[REPOSITORY-URL]` はリポジトリの URL に置き換えます。

   ```bash theme={"system"}
   cws-agent launch [SANDBOX-NAME] --agent cursor --repo-url [REPOSITORY-URL] --lifetime 2h --permission-mode native --no-config-sync
   ```

   Cursor は `/workspace/project` で起動します。ワークスペースの信頼に関するプロンプトが表示された場合は、
   承認してください。`--permission-mode native` を指定すると、Cursor の承認設定がそのまま維持されます。
   指定しない場合、`cws-agent` は `--force` を使用します。`--no-config-sync` を指定すると、
   ローカルのスキルと Model Context Protocol (MCP) の設定はインポートされません。

3. 後で取得できるファイルを作成するよう Cursor に依頼します。

   ```text theme={"system"}
   Create sandbox-proof.txt in the current directory containing exactly
   Hello from CoreWeave followed by a newline, then read it back.
   Do not commit or push anything.
   ```

   タスク中に表示されるプロンプトはすべて承認します。`/exit` で Cursor を終了します。
   ローカルのターミナルでファイルを読み取ります。

   ```bash theme={"system"}
   cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'
   ```

   `Hello from CoreWeave` と出力されれば成功です。Cursor を終了しても、
   サンドボックスは実行されたままです。

4. サンドボックス内のすべての Cursor セッションを終了したら、Cursor が残した
   `worker.sock` ソケットファイルを削除し、ワークスペースを保存してコンピュートを停止します。

   ```bash theme={"system"}
   cws-agent exec [SANDBOX-NAME] 'find /workspace/home/.cursor/projects -type s -name worker.sock -delete'
   cws-agent down [SANDBOX-NAME]
   ```

   このクリーンアップでは、スナップショットの作成を妨げる可能性があるソケットファイルを削除します。`down`
   はサンドボックスを停止する前にスナップショットを作成します。
   スナップショットの作成に失敗した場合、サンドボックスは実行されたままになります。リストアする前に、
   エラーを解決して `down` を再試行してください。

5. 保存済みのワークスペースに戻るには、ローカルで `CURSOR_API_KEY` をエクスポートした状態のまま、次のコマンドを実行します。

   ```bash theme={"system"}
   cws-agent restore [SANDBOX-NAME] --connect --permission-mode native --no-config-sync
   ```

   Cursor に `sandbox-proof.txt` ファイルを読み取るよう依頼し、正しくリストアされたことを検証します。
   作業が完了したら Cursor を終了し、クリーンアップと `down` コマンドを再度実行します。

<h3 id="run-an-unattended-prompt">
  無人でプロンプトを実行する
</h3>

新しいセッション名を選択します。ローカルのターミナルで `--detach` を指定して起動し、ターミナルへのアタッチをスキップしてから、
プロンプトを送信します。

```bash theme={"system"}
cws-agent launch [SANDBOX-NAME] --agent cursor --repo-url [REPOSITORY-URL] --lifetime 2h --permission-mode native --no-config-sync --detach
cws-agent run [SANDBOX-NAME] 'Create sandbox-proof.txt containing exactly Hello from CoreWeave followed by a newline, then read it back. Do not commit or push anything.'
```

`cws-agent run` はデフォルトで Cursor の `--force` フラグを渡すため、ヘッドレスのタスクは対話型の承認なしでファイルを書き込めます。ただし、明示的な拒否ルールは Cursor 側で引き続き適用されます。

実行中のセッションにターミナルをアタッチするには、次のコマンドを実行します。

```bash theme={"system"}
cws-agent connect [SANDBOX-NAME] --permission-mode native --no-config-sync
```

処理が完了したら、Cursor にアタッチしている場合は終了し、`cws-agent exec` で結果を読み取ります。
その後、[cws-agent で Cursor CLI を実行する](#run-cursor-cli-with-cws-agent) に示すとおり、
`cws-agent down` でソケットをクリーンアップして保存します。

<h2 id="run-a-task-with-the-sandbox-sdk">
  Sandboxes SDK でタスクを実行する
</h2>

Sandboxes SDK を使用して、タスクを直接管理します。
この方法では、専用のサンドボックスを作成し、Cursor を print モードで実行してファイルを取得した後、
クリーンアップブロックでサンドボックスを停止します。スナップショットは設定せず、
`cws-agent` も必要ありません。

<h3 id="choose-how-to-supply-the-cursor-key">
  Cursor キーの指定方法を選択する
</h3>

どちらのスクリプトも、第 1 引数として認証モードを受け取ります。

| モード | サンドボックスの認証情報 | Cursor の認証情報 |
| - | - | - |
| `forge` | `FORGE_API_KEY` | Forge のチームシークレット。サーバー側で解決されます。 |
| `coreweave` | `CWSANDBOX_API_KEY` | ローカルの `CURSOR_API_KEY`。サンドボックスの環境マップを介して渡されます。 |

これらの例ではサーバーレス配置を使用します。Forge のシークレット注入を使用するには、Forge 認証とサーバーレス配置が必要です。

`forge` モードを使用する場合は、Forge 管理者に [Cursor キーをチームシークレットとして追加](/ja/products/wandb/platform/secrets#add-a-secret)するよう依頼してください。
ローカルのターミナルで、`[FORGE-TEAM]` をチーム名に、
`[CURSOR-SECRET-NAME]` をシークレット名に置き換えます。

```bash theme={"system"}
export FORGE_API_KEY="[FORGE-API-KEY]"
export FORGE_TEAM="[FORGE-TEAM]"
export CURSOR_SECRET_NAME="[CURSOR-SECRET-NAME]"
```

Forge の APIキーには、そのチームへのアクセス権が必要です。スクリプトは、指定した名前の
シークレットをサンドボックス内の `CURSOR_API_KEY` にマッピングします。詳しくは
[Forge シークレットを使用する](/ja/products/sandboxes/secrets) を参照してください。

`coreweave` モードの場合は、`SANDBOX_USER` IAM action が付与された CoreWeave API アクセストークンを `CWSANDBOX_API_KEY` に設定します。詳しくは [認証情報を選択して取得する](/ja/products/sandboxes/placement#choose-and-get-credentials) を参照してください。続いて、同じローカルターミナルで Cursor キーをエクスポートします。

```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
export CURSOR_API_KEY="[CURSOR-API-KEY]"
```

`coreweave` パスでは、Cursor キーをサンドボックス作成リクエスト内で平文の環境変数値として渡します。これは、認証情報にはシークレット参照を使用するという SDK の推奨事項に対する例外です。このパスは、認証情報の取り扱いに関する組織のポリシーで許可されている場合にのみ使用してください。リクエストをログしたり、キーをコミットしたりしないよう注意してください。

<h3 id="install-a-client">
  クライアントをインストールする
</h3>

言語を選択し、クライアントをローカルにインストールします。

<Tabs>
  <Tab title="Python">
    Python 3.11 以降と `uv` を使用します。新しいプロジェクトディレクトリで次のコマンドを実行します。

    ```bash theme={"system"}
    uv init --python 3.11
    uv add 'cwsandbox==1.14.2'
    ```
  </Tab>

  <Tab title="TypeScript">
    Node.js 22 以降を使用します。プロジェクトディレクトリで次のコマンドを実行します。

    ```bash theme={"system"}
    npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx
    ```
  </Tab>
</Tabs>

<h3 id="create-run-and-clean-up">
  作成、実行、クリーンアップ
</h3>

使用する言語のスクリプトを、記載のファイル名で保存します。各スクリプトは
Cursor をインストールし、コマンドラインで渡されたリポジトリをクローンしたうえで、
`sandbox-proof.txt` ファイルを書き込むよう Cursor に指示します。

`--print`、`--force`、`--trust` フラグは、それぞれ非対話型の出力の有効化、
ファイル変更の許可、ワークスペースの信頼を行います。この
例は、信頼できるリポジトリでのみ使用してください。詳細は
[Cursor headless mode](https://cursor.com/docs/cli/headless) を参照してください。

<Tabs>
  <Tab title="Python">
    ```python title="run_cursor_sandbox.py" theme={"system"}
    import os
    import sys

    from cwsandbox import AuthHeaders, AuthStrategy, Sandbox, Secret

    if len(sys.argv) != 3 or sys.argv[1] not in ("forge", "coreweave"):
        raise SystemExit("Pass forge or coreweave, then a repository URL.")

    mode, repository = sys.argv[1:]
    if mode == "forge":
        auth = AuthHeaders(
            headers={
                "x-wandb-api-key": os.environ["FORGE_API_KEY"],
                "x-entity-id": os.environ["FORGE_TEAM"],
            },
            strategy="wandb_api_key",
        )
        credentials = {"secrets": [Secret(
            store="wandb", name=os.environ["CURSOR_SECRET_NAME"],
            env_var="CURSOR_API_KEY",
        )]}
    else:
        auth = AuthStrategy.COREWEAVE_API_KEY
        credentials = {
            "environment_variables": {"CURSOR_API_KEY": os.environ["CURSOR_API_KEY"]},
        }

    sandbox = Sandbox.run(
        auth=auth,
        placement_mode="serverless",
        container_image="node:22-bookworm",
        resources={"cpu": "2", "memory": "4Gi"},
        max_lifetime_seconds=2 * 3600,
        **credentials,
    )
    try:
        sandbox.wait()
        commands = [
            ["bash", "-o", "pipefail", "-ec", "curl -fsSL https://cursor.com/install | bash"],
            ["mkdir", "-p", "/workspace"],
            ["git", "clone", "--", repository, "/workspace/project"],
        ]
        for command in commands:
            sandbox.exec(command, timeout_seconds=900, check=True).result()

        result = sandbox.exec(
            [
                "/root/.local/bin/agent",
                "--print", "--force", "--trust", "--output-format", "text",
                "Create sandbox-proof.txt containing exactly Hello from CoreWeave "
                "followed by a newline, then read it back. Do not commit or push anything.",
            ],
            cwd="/workspace/project",
            timeout_seconds=300,
            check=True,
        ).result()
        print(result.stdout)
        proof = sandbox.exec(
            ["cat", "/workspace/project/sandbox-proof.txt"], check=True
        ).result()
        print(proof.stdout, end="")
    finally:
        sandbox.stop().result()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript title="run_cursor_sandbox.mts" theme={"system"}
    import { createSandboxClientFromEnv as coreweaveClient } from "@coreweave/cwsandbox/node";
    import { createSandboxClient as forgeClient } from "@coreweave/cwsandbox/wandb";

    const [mode, repository] = process.argv.slice(2);
    if (!repository || (mode !== "forge" && mode !== "coreweave")) {
      throw new Error("Pass forge or coreweave, then a repository URL.");
    }

    const credential = mode === "forge"
      ? process.env.CURSOR_SECRET_NAME : process.env.CURSOR_API_KEY;
    if (!credential) {
      throw new Error("Set CURSOR_SECRET_NAME for forge or CURSOR_API_KEY for coreweave.");
    }
    const client = mode === "forge"
      ? forgeClient({ apiKey: process.env.FORGE_API_KEY, entity: process.env.FORGE_TEAM })
      : coreweaveClient();
    const credentials = mode === "forge"
      ? { secrets: [{ store: "wandb", name: credential, envVar: "CURSOR_API_KEY" }] }
      : { environmentVariables: { CURSOR_API_KEY: credential } };
    const sandbox = await client.create({
      containerImage: "node:22-bookworm",
      resources: { cpu: "2", memory: "4Gi" },
      maxLifetimeSeconds: 2 * 3600,
      ...credentials,
      waitUntilRunning: false,
    });
    try {
      await sandbox.wait();
      const commands = [
        ["bash", "-o", "pipefail", "-ec", "curl -fsSL https://cursor.com/install | bash"],
        ["mkdir", "-p", "/workspace"],
        ["git", "clone", "--", repository, "/workspace/project"],
      ];
      for (const command of commands) {
        await sandbox.commands.run(command, { timeoutMs: 900_000, check: true });
      }

      const result = await sandbox.commands.run(
        [
          "/root/.local/bin/agent",
          "--print", "--force", "--trust", "--output-format", "text",
          "Create sandbox-proof.txt containing exactly Hello from CoreWeave " +
            "followed by a newline, then read it back. Do not commit or push anything.",
        ],
        { cwd: "/workspace/project", timeoutMs: 300_000, check: true },
      );
      console.log(result.stdout);
      const proof = await sandbox.commands.run(
        ["cat", "/workspace/project/sandbox-proof.txt"], { check: true },
      );
      process.stdout.write(proof.stdout);
    } finally {
      await sandbox.stop();
    }
    ```
  </Tab>
</Tabs>

認証情報を設定したローカルのターミナルで、`[AUTH-MODE]` を
`forge` または `coreweave` に、`[REPOSITORY-URL]` をリポジトリの URL に置き換えて実行します。

<Tabs>
  <Tab title="Python">
    ```bash theme={"system"}
    uv run python run_cursor_sandbox.py [AUTH-MODE] [REPOSITORY-URL]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={"system"}
    npx tsx run_cursor_sandbox.mts [AUTH-MODE] [REPOSITORY-URL]
    ```
  </Tab>
</Tabs>

スクリプトは Cursor の応答を出力し、続いてファイルの内容である
`Hello from CoreWeave` を出力します。セットアップや実行の途中でエラーが発生した場合でも、
クリーンアップブロックで必ず `stop()` が呼び出されます。
追加で必要なファイルは、クリーンアップブロックが実行される前に取得してください。結果のサイズが大きい場合は、
[ファイル操作](/ja/products/sandboxes/client/guides/file-operations)を使用してください。

2 時間の有効期間は、起動時間を含む実時間の上限です。また、各
コマンドにも個別のタイムアウトが設定されています。コマンドのタイムアウトを変更しても、
サンドボックスのライフタイムは延長されません。

<h2 id="troubleshoot">
  トラブルシューティング
</h2>

よくある問題は、次の点を確認して解決してください。

* サンドボックスの作成に失敗する場合は、選択した
  認証モードの認証情報を確認してください。

* Forge シークレットを解決できない場合は、`FORGE_TEAM`、`CURSOR_SECRET_NAME`、
  および APIキーのチームへのアクセス権を確認してください。

* Cursor で認証エラーが発生する場合は、モードに応じて Forge シークレットまたはローカルの `CURSOR_API_KEY` に設定されたキーを検証し、アカウントにモデルへのアクセス権があるかどうかを確認してください。

* SDK のプロンプトで変更が提案されるだけの場合は、Cursor のコマンドに
  `--force` が含まれていることを確認してください。

* インストール、クローン、またはモデルへのリクエストが失敗する場合は、アウトバウンドの接続性
  とプロバイダーの認証情報を確認してください。CoreWeave Kubernetes Service (CKS) に配置する場合は、
  ランナーのポリシーで必要な送信先が許可されている必要があります。

<h2 id="next-steps">
  次のステップ
</h2>

詳細については、次のガイドを参照してください。

* [CoreWeave サンドボックスでエージェントを実行する](/ja/products/sandboxes/agents) では、配置、
  長時間のセッション、ワークスペースのライフサイクルについて説明しています。
* [cws-agent で Cursor を使用する](https://github.com/coreweave/cws-agent/blob/main/docs/cursor.md)
  では、保存済みの会話と設定のインポートについて説明しています。
* [Cursor CLI のドキュメント](https://cursor.com/docs/cli/overview) では、エージェントの
  設定とサポートされているモードについて説明しています。