Exécuter Cursor dans une sandbox

Exécutez l’interface de ligne de commande (CLI) de Cursor sur un dépôt dans une sandbox CoreWeave. Connectez votre terminal pour travailler de manière interactive, ou exécutez un prompt via le kit de développement logiciel (SDK) Sandboxes et récupérez le résultat. Le processus de la CLI, le workspace et les commandes s’exécutent dans la sandbox. Les requêtes adressées au modèle sont envoyées à Cursor. Cursor prend également en charge les Self-Hosted Machines : le cloud de Cursor y exécute la boucle de l’agent, tandis qu’un worker distinct exécute les appels d’outils.

Prérequis

Avant de commencer, vous devez disposer des éléments suivants :

Un jeton d’accès à l’API CoreWeave disposant de l’action SANDBOX_USER pour le chemin cws-agent. Le SDK prend également en charge une clé API Forge pour l’injection de secrets ; voir Choisir comment fournir la clé Cursor.
Une clé API utilisateur Cursor et un accès à un modèle pris en charge par la CLI Cursor.
L’URL d’un dépôt public. Les dépôts privés nécessitent des identifiants d’authentification Git dans la sandbox.
Une connectivité sortante vers Cursor, son hôte de téléchargement et votre hôte Git.

Dans votre terminal local, définissez votre jeton d’accès à l’API CoreWeave :

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

Cursor lit CURSOR_API_KEY dans la sandbox. Cursor peut transmettre des prompts, le contenu des fichiers et la sortie des outils à son service. Utilisez un dépôt et des identifiants d’authentification adaptés à la tâche.

Exécuter Cursor CLI avec cws-agent

Utilisez cws-agent pour créer une sandbox, y installer Cursor et y attacher votre terminal. L’attachement interactif nécessite un terminal interactif (TTY) sous macOS, Linux ou Windows Subsystem for Linux (WSL). Les terminaux Windows natifs ne sont pas pris en charge. Exportez votre clé Cursor en local. cws-agent la transmet à l’environnement de la sandbox :

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

Suivez les instructions d’installation de cws-agent.
Remplacez [SANDBOX-NAME] par un nom de session comprenant de 1 à 40 lettres minuscules, chiffres ou traits d’union, et commençant par une lettre ou un chiffre. Remplacez [REPOSITORY-URL] par l’URL de votre dépôt :
cws-agent launch [SANDBOX-NAME] --agent cursor --repo-url [REPOSITORY-URL] --lifetime 2h --permission-mode native --no-config-sync
Cursor s’ouvre dans /workspace/project. Si une invite vous demande de faire confiance au workspace, acceptez-la. --permission-mode native conserve les paramètres d’approbation de Cursor ; sans cette option, cws-agent utilise --force. --no-config-sync évite d’importer vos skills locaux et votre configuration Model Context Protocol (MCP).
Demandez à Cursor de créer un fichier que vous pourrez récupérer :
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.
Approuvez toutes les invites liées à la tâche. Quittez Cursor avec /exit. Dans votre terminal local, lisez le fichier :
cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'
La sortie doit être Hello from CoreWeave. Quitter Cursor n’arrête pas la sandbox.
Après avoir quitté toutes les sessions Cursor dans la sandbox, supprimez les fichiers de socket worker.sock laissés par Cursor, enregistrez le workspace et arrêtez les ressources de calcul :
cws-agent exec [SANDBOX-NAME] 'find /workspace/home/.cursor/projects -type s -name worker.sock -delete' cws-agent down [SANDBOX-NAME]
Le nettoyage supprime les fichiers de socket susceptibles de bloquer la création d’instantanés. down prend un instantané avant d’arrêter la sandbox. Si la création de l’instantané échoue, la sandbox continue de s’exécuter. Corrigez l’erreur et relancez down avant toute restauration.
Pour revenir au workspace enregistré, gardez la variable CURSOR_API_KEY exportée localement et exécutez :
cws-agent restore [SANDBOX-NAME] --connect --permission-mode native --no-config-sync
Demandez à Cursor de lire le fichier sandbox-proof.txt pour vérifier qu’il a bien été restauré. Lorsque vous avez terminé, quittez Cursor et répétez les commandes de nettoyage et down.

Exécuter un prompt sans surveillance

Choisissez un nouveau nom de session. Dans votre terminal local, lancez la commande avec --detach pour ne pas vous rattacher au terminal, puis envoyez un 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.'

Par défaut, cws-agent run transmet l’option --force de Cursor afin que la tâche headless puisse écrire des fichiers sans validation interactive. Les règles de refus explicites de Cursor restent appliquées. Pour attacher votre terminal à la session en cours d’exécution, exécutez :

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

Une fois l’opération terminée, quittez Cursor si vous y êtes attaché, lisez le résultat avec cws-agent exec, puis nettoyez les sockets et enregistrez avec cws-agent down, comme indiqué dans Exécuter Cursor CLI avec cws-agent.

Exécuter une tâche avec le SDK Sandboxes

Utilisez le SDK Sandboxes pour gérer directement une tâche. Cette approche crée une sandbox dédiée, exécute Cursor en mode print, récupère le fichier, puis arrête la sandbox dans un bloc de nettoyage. Elle ne configure pas d’instantanés et ne requiert pas cws-agent.

Choisir comment fournir la clé Cursor

Les deux scripts prennent un mode d’authentification comme premier argument :

Mode	Identifiant d’authentification de la sandbox	Identifiant d’authentification Cursor
`forge`	`FORGE_API_KEY`	Un secret d’équipe Forge, résolu par le serveur.
`coreweave`	`CWSANDBOX_API_KEY`	Variable `CURSOR_API_KEY` locale, transmise via la table des variables d’environnement de la sandbox.

Ces exemples utilisent le placement sans serveur. L’injection de secrets Forge nécessite l’authentification Forge et le placement sans serveur. Pour le mode forge, demandez à un administrateur Forge d’ajouter votre clé Cursor en tant que secret d’équipe. Dans votre terminal local, remplacez [FORGE-TEAM] par le nom de votre équipe et [CURSOR-SECRET-NAME] par le nom du secret :

export FORGE_API_KEY="[FORGE-API-KEY]"
export FORGE_TEAM="[FORGE-TEAM]"
export CURSOR_SECRET_NAME="[CURSOR-SECRET-NAME]"

Votre clé API Forge doit avoir accès à cette équipe. Les scripts mappent le secret nommé sur CURSOR_API_KEY dans la sandbox. Voir Utiliser les secrets Forge. Pour le mode coreweave, définissez CWSANDBOX_API_KEY sur un jeton d’accès à l’API CoreWeave disposant de l’action IAM SANDBOX_USER. Voir Choisir et obtenir des identifiants d’authentification. Exportez votre clé Cursor dans ce même terminal local :

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
export CURSOR_API_KEY="[CURSOR-API-KEY]"

Le chemin coreweave transmet la clé Cursor sous forme de valeur d’environnement en clair dans la requête de création de la sandbox. Il s’agit d’une exception à la recommandation du SDK, qui préconise d’utiliser des références de secret pour les identifiants d’authentification. N’utilisez ce chemin que si votre politique de gestion des identifiants d’authentification l’autorise. Évitez de journaliser la requête ou de versionner la clé.

Installer un client

Choisissez un langage et installez le client en local :

Python
TypeScript

Utilisez Python 3.11 ou version ultérieure, ainsi que uv. Dans un nouveau répertoire de projet, exécutez :

uv init --python 3.11
uv add 'cwsandbox==1.14.2'

Utilisez Node.js 22 ou version ultérieure. Dans le répertoire de votre projet, exécutez :

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

Créer, exécuter et nettoyer

Enregistrez le script correspondant à votre langage sous le nom de fichier indiqué. Chaque script installe Cursor, clone le dépôt passé en ligne de commande, puis demande à Cursor d’écrire le fichier sandbox-proof.txt. Les options --print, --force et --trust activent une sortie non interactive, autorisent la modification des fichiers et marquent le workspace comme fiable. N’utilisez cet exemple qu’avec un dépôt de confiance. Voir le mode headless de Cursor.

Python
TypeScript

run_cursor_sandbox.py

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

run_cursor_sandbox.mts

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

Dans le terminal local où vous avez défini vos identifiants d’authentification, remplacez [AUTH-MODE] par forge ou coreweave, 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]

Le script affiche la réponse de Cursor, suivie du contenu du fichier, Hello from CoreWeave. Le bloc de nettoyage appelle stop() même si la configuration ou l’exécution lève une erreur. Récupérez les éventuels fichiers supplémentaires avant l’exécution du bloc de nettoyage. Pour des résultats plus volumineux, utilisez les opérations sur les fichiers. La durée de vie de 2 heures correspond à une durée maximale en temps réel, démarrage compris. Chaque commande dispose en outre de son propre délai d’expiration. Modifier le délai d’expiration d’une commande ne prolonge pas la durée de vie du bac à sable.

Dépannage

Effectuez les vérifications suivantes pour résoudre les problèmes courants :

Si la création de la sandbox échoue, vérifiez l’identifiant d’authentification associé au mode d’authentification sélectionné.
Si un secret Forge ne peut pas être résolu, vérifiez FORGE_TEAM, 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é dans votre secret Forge ou dans la variable locale CURSOR_API_KEY, selon le mode, et assurez-vous que votre compte a accès au modèle.
Si un prompt du SDK se contente de proposer des modifications, assurez-vous que la commande Cursor inclut --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. Pour un placement sur CoreWeave Kubernetes Service (CKS), la politique de votre exécuteur doit autoriser les destinations requises.

Étapes suivantes

Pour plus d’informations, consultez les guides suivants :

Exécuter des agents sur les bacs à sable CoreWeave aborde le placement, les sessions plus longues et le cycle de vie du workspace.
Cursor avec cws-agent aborde les conversations enregistrées et l’importation de configurations.
Documentation de la CLI Cursor aborde la configuration de l’agent et les modes pris en charge.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Exécuter Cursor dans une sandbox

Prérequis

Exécuter Cursor CLI avec cws-agent

Exécuter un prompt sans surveillance

Exécuter une tâche avec le SDK Sandboxes

Choisir comment fournir la clé Cursor

Installer un client

Créer, exécuter et nettoyer

Dépannage

Étapes suivantes

​Prérequis

​Exécuter Cursor CLI avec cws-agent

​Exécuter un prompt sans surveillance

​Exécuter une tâche avec le SDK Sandboxes

​Choisir comment fournir la clé Cursor

​Installer un client

​Créer, exécuter et nettoyer

​Dépannage

​Étapes suivantes

Prérequis

Exécuter Cursor CLI avec cws-agent

Exécuter un prompt sans surveillance

Exécuter une tâche avec le SDK Sandboxes

Choisir comment fournir la clé Cursor

Installer un client

Créer, exécuter et nettoyer

Dépannage

Étapes suivantes