Exécuter Cursor dans un sandbox

Run the Cursor command-line interface (CLI) against a repository in a CoreWeave sandbox. Attach your terminal for interactive work, or run a prompt through the Sandbox software development kit (SDK) and collect the result. The CLI process, workspace, and commands run in the sandbox. Model requests go to Cursor. Cursor also supports Self-Hosted Machines, where Cursor’s cloud runs the agent loop and a separate worker executes tool calls.

Prerequisites

Before you begin, you need the following:

Une clé API W&B avec un accès aux sandboxes.

A Cursor user API key and access to a model supported by Cursor CLI.
A public repository URL. Private repositories require Git credentials inside the sandbox.
Outbound connectivity to Cursor, its download host, and your Git host.

In your local terminal, set the sandbox credential you want to use:

export WANDB_API_KEY="[WANDB-API-KEY]"
unset CWSANDBOX_API_KEY

Si vous supprimez la variable CWSANDBOX_API_KEY, cws-agent utilise l’authentification W&B. Cursor reads CURSOR_API_KEY inside the sandbox. Cursor can send prompts, file contents, and tool output to its service. Use a repository and credentials appropriate for the task.

Run Cursor CLI with cws-agent

Use cws-agent to create a sandbox, install Cursor, and attach your terminal. Interactive attachment requires an interactive terminal (TTY) on macOS, Linux, or Windows Subsystem for Linux (WSL). Native Windows terminals aren’t supported. Export your Cursor key locally. cws-agent forwards it into the sandbox’s environment:

export CURSOR_API_KEY="[CURSOR-API-KEY]"

Follow the cws-agent installation instructions.
Replace [SANDBOX-NAME] with a session name containing 1 to 40 lowercase letters, digits, or hyphens, starting with a letter or digit. Replace [REPOSITORY-URL] with your repository URL:
cws-agent launch [SANDBOX-NAME] --agent cursor --repo-url [REPOSITORY-URL] --lifetime 2h --permission-mode native --no-config-sync
Cursor opens in /workspace/project. If a workspace trust prompt appears, accept it. --permission-mode native retains Cursor’s approval settings. cws-agent otherwise uses --force. --no-config-sync skips importing your local skills and Model Context Protocol (MCP) configuration.

Ask Cursor to create a file you can retrieve:

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.

Approve any prompts for the task. Exit Cursor with /exit. In your local terminal, read the file:

cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'

The output should be Hello from CoreWeave. Exiting Cursor leaves the sandbox running.

After exiting all Cursor sessions in the sandbox, remove Cursor’s leftover worker.sock socket files, save the workspace, and stop compute:
cws-agent exec [SANDBOX-NAME] 'find /workspace/home/.cursor/projects -type s -name worker.sock -delete' cws-agent down [SANDBOX-NAME]
The cleanup removes socket files that can block snapshot creation. down takes a snapshot before stopping the sandbox. If snapshot creation fails, the sandbox stays running. Resolve the error and retry down before restoring.
To return to the saved workspace, keep CURSOR_API_KEY exported locally and run:
cws-agent restore [SANDBOX-NAME] --connect --permission-mode native --no-config-sync
Ask Cursor to read the sandbox-proof.txt file to verify that it was restored. When finished, exit Cursor and repeat the cleanup and down commands.

Run an unattended prompt

Choose a new session name. In your local terminal, launch with --detach to skip terminal attachment, then send a prompt:

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 passes Cursor’s --force flag by default so the headless task can write files without interactive approval. Cursor retains explicit deny rules. To attach your terminal to the running session, run:

cws-agent connect [SANDBOX-NAME] --permission-mode native --no-config-sync

When finished, exit Cursor if attached, read the result with cws-agent exec, then clean up the sockets and save with cws-agent down as shown in Run Cursor CLI with cws-agent.

Run a task with the Sandbox SDK

Use the Sandbox SDK to manage a task directly. This path creates a separate sandbox, runs Cursor in print mode, retrieves the file, and stops the sandbox in a cleanup block. It doesn’t configure snapshots or require cws-agent.

Choose how to supply the Cursor key

Both scripts take an authentication mode as their first argument:

Mode	Identifiant d’authentification du sandbox	Identifiant d’authentification Cursor
`wandb`	`WANDB_API_KEY`	Un secret d’équipe W&B, résolu par le serveur.

L’injection de secrets W&B nécessite l’authentification W&B et un placement serverless. Demandez à un administrateur W&B d’ajouter votre clé Cursor en tant que secret d’équipe. Dans votre terminal local, remplacez [WANDB-TEAM] par le nom de votre équipe et [CURSOR-SECRET-NAME] par le nom du secret :

export WANDB_ENTITY="[WANDB-TEAM]"
export CURSOR_SECRET_NAME="[CURSOR-SECRET-NAME]"

Votre clé API W&B doit avoir accès à cette équipe. Les scripts associent le secret indiqué à CURSOR_API_KEY dans la sandbox. Voir Utiliser les secrets W&B.

Install a client

Choose a language and install the client locally:

Python
TypeScript

Use Python 3.11 or later and uv. In a new project directory, run:

uv init --python 3.11
uv add 'cwsandbox[wandb]==1.14.2'

Use Node.js 22 or later. In your project directory, run:

npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx

Create, run, and clean up

Save the script for your language using the filename shown. Each script installs Cursor, clones the repository passed on the command line, and asks Cursor to write the sandbox-proof.txt file. The --print, --force, and --trust flags enable non-interactive output, permit file changes, and trust the workspace. Use this example only with a repository you trust. See Cursor headless mode.

Python
TypeScript

run_cursor_sandbox.py

import os
import sys

from cwsandbox import AuthStrategy, Sandbox, Secret

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

mode, repository = sys.argv[1:]
if mode == "wandb":
    auth = AuthStrategy.WANDB
    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()

run_cursor_sandbox.mts

import { createSandboxClientFromEnv as coreweaveClient } from "@coreweave/cwsandbox/node";
import { createSandboxClientFromEnv as wandbClient } from "@coreweave/cwsandbox/wandb";

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

const credential = mode === "wandb"
  ? process.env.CURSOR_SECRET_NAME : process.env.CURSOR_API_KEY;
if (!credential) {
  throw new Error("Set CURSOR_SECRET_NAME for wandb or CURSOR_API_KEY for coreweave.");
}
const client = mode === "wandb" ? wandbClient() : coreweaveClient();
const credentials = mode === "wandb"
  ? { 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();
}

Dans le terminal local où vous avez défini vos identifiants d’authentification, remplacez [AUTH-MODE] par wandb et [REPOSITORY-URL] par l’URL de votre dépôt :

Python
TypeScript

uv run python run_cursor_sandbox.py [AUTH-MODE] [REPOSITORY-URL]

npx tsx run_cursor_sandbox.mts [AUTH-MODE] [REPOSITORY-URL]

The script prints Cursor’s response followed by the file contents, Hello from CoreWeave. The cleanup block calls stop() even if setup or execution raises an error. Retrieve any additional files before the cleanup block runs. For larger results, use file operations. The 2-hour lifetime is a maximum wall-clock limit, including startup. Each command also has its own timeout. Changing the command timeout doesn’t extend the sandbox lifetime.

Troubleshoot

Use these checks to resolve common issues:

If sandbox creation fails, verify the credential for your selected authentication mode.

Si un secret W&B ne peut pas être résolu, vérifiez WANDB_ENTITY, CURSOR_SECRET_NAME ainsi que l’accès de votre clé API à l’équipe.
Si Cursor signale une erreur d’authentification, vérifiez la clé contenue dans votre secret W&B ainsi que l’accès de votre compte aux modèles.

If an SDK prompt only proposes changes, confirm that the Cursor command includes --force.

Si l’installation, le clonage ou les requêtes au modèle échouent, vérifiez la connectivité sortante et les identifiants d’authentification du fournisseur.

Next steps

For more information, see these guides:

Run agents on CoreWeave sandboxes covers placement, longer sessions, and workspace lifecycle.
Cursor with cws-agent covers saved conversations and configuration imports.
Cursor CLI documentation covers agent configuration and supported modes.

​Prerequisites

​Run Cursor CLI with cws-agent

​Run an unattended prompt

​Run a task with the Sandbox SDK

​Choose how to supply the Cursor key

​Install a client

​Create, run, and clean up

​Troubleshoot

​Next steps