Client TypeScript pour Sandbox

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. Les exemples utilisent la capacité sans serveur. Pour un placement sur CoreWeave Kubernetes Service (CKS), activez un exécuteur et utilisez un jeton d’accès à l’API CoreWeave doté d’un tableau runnerIds non vide. Installez le SDK :

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

Clé API Forge
Jeton d’accès à l’API CoreWeave

Remplacez [WANDB-API-KEY] par votre clé API Forge :

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

sandbox-client.mts

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.

Remplacez [API-ACCESS-TOKEN] par votre jeton :

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

sandbox-client.mts

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.

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.

hello.mts

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 :

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

Gérer les erreurs

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

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.

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	Créer, se reconnecter, lister, nettoyer et démarrer à partir de modèles ou de fichiers Compose.
Sandbox et cycle de vie	Handles de sandbox, options de démarrage, instantanés et états du cycle de vie.
Commandes et terminaux	Exécution de commandes, handles de processus, entrée standard (stdin) et terminaux interactifs.
Fichiers	Opérations sur les fichiers en mémoire tampon ou en diffusion en continu, et fichiers montés.
Journaux	Lire les journaux de la sandbox et les diffuser en continu.
Réseaux et services	Règles réseau, services et points de terminaison.
Ressources et secrets	Demandes de ressources, limites et secrets en entrée.
Options de requête et valeurs par défaut	Délais d’expiration, annulation, modes du plan de données et constantes par défaut.
Erreurs	Classes d’erreurs, codes et constantes de motifs du backend.
Fabriques de clients Node	Authentification par jeton CoreWeave et construction du client.
Fabriques de clients Forge	Authentification Forge et sélection de l’équipe.

Pour un exemple Compose, consultez Créer une sandbox depuis TypeScript.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Client TypeScript pour Sandbox

Prérequis

Créer un client

Exécuter une commande

Gérer les erreurs

Référence de l’API

​Prérequis

​Créer un client

​Exécuter une commande

​Gérer les erreurs

​Référence de l’API

Prérequis

Créer un client

Exécuter une commande

Gérer les erreurs

Référence de l’API