> ## 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.

# Exécuter Cursor dans une sandbox

> Exécutez Cursor CLI de manière interactive ou automatisez des tâches de développement dans une sandbox CoreWeave.

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](https://cursor.com/docs/cloud-agent/self-hosted) :
le cloud de Cursor y exécute la boucle de l’agent, tandis qu’un worker distinct exécute les appels d’outils.

<h2 id="prerequisites">
  Prérequis
</h2>

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

* Un [jeton d’accès à l’API CoreWeave](/fr/products/sandboxes/get-started#coreweave-api-access-token) 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](#choose-how-to-supply-the-cursor-key).

* Une [clé API utilisateur Cursor](https://cursor.com/docs/cli/reference/authentication#api-key-authentication)
  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 :

```bash theme={"system"}
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.

<h2 id="run-cursor-cli-with-cws-agent">
  Exécuter Cursor CLI avec cws-agent
</h2>

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 :

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

1. Suivez les [instructions d’installation de `cws-agent`](https://github.com/coreweave/cws-agent#install).

2. 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 :

   ```bash theme={"system"}
   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).

3. Demandez à Cursor de créer un fichier que vous pourrez récupérer :

   ```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.
   ```

   Approuvez toutes les invites liées à la tâche. Quittez Cursor avec `/exit`.
   Dans votre terminal local, lisez le fichier :

   ```bash theme={"system"}
   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.

4. 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 :

   ```bash theme={"system"}
   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.

5. Pour revenir au workspace enregistré, gardez la variable `CURSOR_API_KEY` exportée localement et exécutez :

   ```bash theme={"system"}
   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`.

<h3 id="run-an-unattended-prompt">
  Exécuter un prompt sans surveillance
</h3>

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 :

```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.'
```

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 :

```bash theme={"system"}
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](#run-cursor-cli-with-cws-agent).

<h2 id="run-a-task-with-the-sandbox-sdk">
  Exécuter une tâche avec le SDK Sandboxes
</h2>

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`.

<h3 id="choose-how-to-supply-the-cursor-key">
  Choisir comment fournir la clé Cursor
</h3>

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](/fr/products/wandb/platform/secrets#add-a-secret).
Dans votre terminal local, remplacez `[FORGE-TEAM]` par le nom de votre équipe et
`[CURSOR-SECRET-NAME]` par le nom du secret :

```bash theme={"system"}
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](/fr/products/sandboxes/secrets).

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](/fr/products/sandboxes/placement#choose-and-get-credentials). Exportez votre clé Cursor dans ce même terminal local :

```bash theme={"system"}
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é.

<h3 id="install-a-client">
  Installer un client
</h3>

Choisissez un langage et installez le client en local :

<Tabs>
  <Tab title="Python">
    Utilisez Python 3.11 ou version ultérieure, ainsi que `uv`. Dans un nouveau répertoire de projet, exécutez :

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

  <Tab title="TypeScript">
    Utilisez Node.js 22 ou version ultérieure. Dans le répertoire de votre projet, exécutez :

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

<h3 id="create-run-and-clean-up">
  Créer, exécuter et nettoyer
</h3>

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

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 :

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

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](/fr/products/sandboxes/client/guides/file-operations).

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.

<h2 id="troubleshoot">
  Dépannage
</h2>

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.

<h2 id="next-steps">
  Étapes suivantes
</h2>

Pour plus d'informations, consultez les guides suivants :

* [Exécuter des agents sur les bacs à sable CoreWeave](/fr/products/sandboxes/agents) aborde le placement,
  les sessions plus longues et le cycle de vie du workspace.
* [Cursor avec cws-agent](https://github.com/coreweave/cws-agent/blob/main/docs/cursor.md)
  aborde les conversations enregistrées et l'importation de configurations.
* [Documentation de la CLI Cursor](https://cursor.com/docs/cli/overview) aborde la configuration
  de l'agent et les modes pris en charge.