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

# Client TypeScript pour Sandbox

> Créez des Sandbox, exécutez des commandes et consultez l’API du kit de développement logiciel (SDK) TypeScript.

Le client TypeScript `@coreweave/cwsandbox` permet de créer et de gérer des Sandbox CoreWeave. Ce guide explique comment créer un client, exécuter une commande dans une sandbox et gérer les erreurs du SDK. Les exemples TypeScript de Sandbox et la référence de l’API s’appuient sur la version 1.0.0. Installez cette version pour suivre les guides.

## Prérequis

Utilisez Node.js 22 ou une version ultérieure, ainsi qu’un projet de module ECMAScript (ESM). Enregistrez les exemples sous forme de fichiers `.mts` pour les exécuter avec `tsx`.

Choisissez un identifiant d’authentification parmi ceux présentés dans la section [Choisir et obtenir des identifiants](https://docs.coreweave.com/fr/products/sandboxes/placement.md#choose-and-get-credentials). Les exemples utilisent la capacité sans serveur. Pour un placement sur CoreWeave Kubernetes Service (CKS), [activez un exécuteur](https://docs.coreweave.com/fr/products/sandboxes/get-started-cks.md) et utilisez un jeton d’accès à l’API CoreWeave doté d’un tableau `runnerIds` non vide.

Installez le SDK :

```bash theme={"system"}
npm install @coreweave/cwsandbox@1.0.0
```

## Créer un client

Choisissez le point d’entrée correspondant à votre identifiant d’authentification. Les deux fabriques renvoient un [`SandboxClient`](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/client#sandboxclient). Le point d’entrée racine `@coreweave/cwsandbox` exporte les types, les constantes et les erreurs. Pour créer des clients, passez par `/wandb` ou `/node`.

Enregistrez le code de l’onglet correspondant dans un fichier `sandbox-client.mts`, à côté des autres fichiers d’exemple. Ce code sélectionne le mode d’authentification et exporte le client. L’identifiant d’authentification reste dans votre environnement.

> [tab] Clé API Forge
>
> Remplacez `[WANDB-API-KEY]` par votre clé API Forge :
>
> ```bash theme={"system"}
> export WANDB_API_KEY="[WANDB-API-KEY]"
> ```
>
> ```typescript title="sandbox-client.mts" theme={"system"}
> import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";
>
> export const client = createSandboxClientFromEnv();
> ```
>
> Pour sélectionner une équipe Forge, définissez `WANDB_ENTITY`. Pour transmettre les options de manière explicite, consultez [Fabriques de clients Forge](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/wandb.md).

> [tab] Jeton d’accès à l’API CoreWeave
>
> Remplacez `[API-ACCESS-TOKEN]` par votre jeton :
>
> ```bash theme={"system"}
> export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
> ```
>
> ```typescript title="sandbox-client.mts" theme={"system"}
> import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";
>
> export const client = createSandboxClientFromEnv();
> ```
>
> La fabrique lit également `CWSANDBOX_BASE_URL`, dont la valeur par défaut est `https://api.cwsandbox.com`. Pour transmettre les options de manière explicite, consultez [Fabriques de clients Node](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/node.md).

## Exécuter une commande

Pour les tâches qui doivent s’arrêter lorsque leur fonction de rappel se termine, utilisez `withSandbox()`. Cette méthode attend que la sandbox soit prête avant d’appeler la fonction de rappel, puis arrête la sandbox dès que la fonction de rappel a renvoyé une valeur ou levé une exception.

```typescript title="hello.mts" theme={"system"}
import { client } from "./sandbox-client.mjs";

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
  },
);

console.log(result.stdout);
```

Exécutez le script :

```bash theme={"system"}
npx --yes --package=tsx tsx hello.mts
```

Le script affiche `Hello!` et arrête la sandbox.

L’import `./sandbox-client.mjs` est résolu vers le fichier local `sandbox-client.mts` lorsque vous exécutez le script avec `tsx` ou que vous le compilez avec TypeScript.

`commands.run()` place la sortie standard (stdout) et la sortie d’erreur standard (stderr) en mémoire tampon, puis renvoie un [`ProcessResult`](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/commands#processresult) contenant `exitCode`. Pour obtenir la sortie en diffusion en continu, utilisez `commands.start()`.

Pour conserver la sandbox d’une opération à l’autre, utilisez `client.create()`, puis arrêtez-la dans un bloc `finally`. Voir la [référence sur le cycle de vie de la sandbox](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/sandboxes.md#sandbox).

## Gérer les erreurs

Utilisez `isCWSandboxError()` pour affiner le type d’une erreur inconnue et examiner son `code` :

```typescript theme={"system"}
import { isCWSandboxError } from "@coreweave/cwsandbox";
import { client } from "./sandbox-client.mjs";

try {
  await client.withSandbox(async (sandbox) => {
    await sandbox.commands.run(["false"], { check: true });
  });
} catch (error) {
  if (isCWSandboxError(error)) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}
```

Avec `check: true`, une commande qui se termine avec un code de sortie non nul lève une exception `CWSandboxExecutionError`. Pour connaître la hiérarchie des erreurs et les métadonnées disponibles, consultez [Erreurs](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/errors.md).

## Référence de l’API

La référence reprend les déclarations publiées, y compris les surcharges de méthodes, les types de paramètres et de retour, les champs facultatifs et les types hérités. Les commentaires du SDK intègrent des corrections relues.

| Référence | Contenu |
| - | - |
| [Client et découverte](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/client.md) | Créer, se reconnecter, lister, nettoyer et démarrer à partir de modèles ou de fichiers Compose. |
| [Sandbox et cycle de vie](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/sandboxes.md) | Handles de sandbox, options de démarrage, instantanés et états du cycle de vie. |
| [Commandes et terminaux](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/commands.md) | Exécution de commandes, handles de processus, entrée standard (stdin) et terminaux interactifs. |
| [Fichiers](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/files.md) | Opérations sur les fichiers en mémoire tampon ou en diffusion en continu, et fichiers montés. |
| [Journaux](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/logs.md) | Lire les journaux de la sandbox et les diffuser en continu. |
| [Réseaux et services](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/network.md) | Règles réseau, services et points de terminaison. |
| [Ressources et secrets](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/resources.md) | Demandes de ressources, limites et secrets en entrée. |
| [Options de requête et valeurs par défaut](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/common.md) | Délais d’expiration, annulation, modes du plan de données et constantes par défaut. |
| [Erreurs](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/errors.md) | Classes d’erreurs, codes et constantes de motifs du backend. |
| [Fabriques de clients Node](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/node.md) | Authentification par jeton CoreWeave et construction du client. |
| [Fabriques de clients Forge](https://docs.coreweave.com/fr/products/sandboxes/typescript-client/ref/wandb.md) | Authentification Forge et sélection de l’équipe. |

Pour un exemple Compose, consultez [Créer une sandbox depuis TypeScript](https://docs.coreweave.com/fr/products/sandboxes/create-from-file.md#create-a-sandbox-from-typescript).