Run Cursor in a CoreWeave 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.

CoreWeave Serverless sandboxes are in public preview.

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:

A W&B API key or CoreWeave API access token with sandbox access. See Choose a credential.
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:

W&B API key
CoreWeave API access token

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

Unsetting CWSANDBOX_API_KEY makes cws-agent select W&B authentication.

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

cws-agent selects this token when CWSANDBOX_API_KEY is set.

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	Sandbox credential	Cursor credential
`wandb`	`WANDB_API_KEY`	A W&B team secret, resolved by the server.
`coreweave`	`CWSANDBOX_API_KEY`	Local `CURSOR_API_KEY`, passed through the sandbox environment map.

W&B secret injection requires W&B authentication and serverless placement. It isn’t available with a CoreWeave API access token. These examples use serverless placement for both modes.

W&B secret
CoreWeave environment injection

Ask a W&B administrator to add your Cursor key as a team secret. In your local terminal, replace [WANDB-TEAM] with your team name and [CURSOR-SECRET-NAME] with the secret name:

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

Your W&B API key must have access to that team. The scripts map the named secret to CURSOR_API_KEY inside the sandbox. See Use W&B secrets.

Export your Cursor key in the local terminal:

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

This quickstart passes the key as a plain environment value in the sandbox creation request. This is an exception to the SDK’s recommendation to use secret references for credentials. Use this path only if your credential-handling policy permits it. Avoid logging the request or committing the key.

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();
}

In the local terminal where you set your credentials, replace [AUTH-MODE] with wandb or coreweave, and [REPOSITORY-URL] with your repository URL:

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.
If a W&B secret can’t be resolved, check WANDB_ENTITY, CURSOR_SECRET_NAME, and your API key’s team access.
If Cursor reports an authentication error, verify the key in your W&B secret or local CURSOR_API_KEY, and check your account’s model access.
If an SDK prompt only proposes changes, confirm that the Cursor command includes --force.
If installation, cloning, or model requests fail, check outbound connectivity and provider credentials. For CoreWeave Kubernetes Service (CKS) placement, your runner policy must allow the required destinations.

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

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