Placement et basculement des sandbox

Le placement détermine sur quelles ressources de calcul s’exécute votre sandbox. Le mode sans serveur s’appuie sur des ressources de calcul managées par CoreWeave. Le placement en cluster utilise les ressources de calcul d’un cluster CoreWeave Kubernetes Service (CKS) de votre organisation. En cas d’échec du placement initial, le basculement relance la création de la sandbox dans l’autre mode.

Comparer les modes de placement

Choisissez un mode selon l’entité qui gère la capacité et la politique :

	Sans serveur	CKS
Où s’exécutent les bacs à sable	Ressources de calcul managées par CoreWeave	Ressources de calcul de votre cluster CKS
Qui configure la politique	CoreWeave	Vos administrateurs
Configuration	Authentifiez-vous avec un identifiant d’authentification Forge ou CoreWeave	Activez un exécuteur sur le cluster
Contrôle du placement	Géré par la plateforme. Vous ne sélectionnez pas de cluster.	En Python, n’importe quel cluster éligible peut être utilisé. Spécifiez des ID d’exécuteur pour restreindre le placement. En TypeScript, les ID d’exécuteur sont obligatoires.
Ressources	Choisissez le CPU et la mémoire de chaque sandbox	Choisissez le CPU et la mémoire dans les limites de la politique de votre cluster
Identifiants d’authentification	Clé API Forge ou jeton d’accès à l’API CoreWeave	Jeton d’accès à l’API CoreWeave
Quand l’utiliser	Pour exécuter des bacs à sable sans gérer la capacité d’un cluster	Pour utiliser la capacité de votre cluster et contrôler les politiques de ressources et de réseau

Pour créer votre premier sandbox, suivez le démarrage rapide sans serveur ou le guide Utiliser vos propres ressources de calcul.

Choisir et obtenir des identifiants d’authentification

Votre identifiant d’authentification détermine le compte propriétaire du sandbox, auquel son utilisation est facturée. Les clés API Forge fonctionnent avec les bacs à sable sans serveur. Les jetons d’accès à l’API CoreWeave fonctionnent à la fois avec les bacs à sable sans serveur et avec les bacs à sable de cluster.

Clé API Forge

Choisissez une clé API Forge si vous n’avez pas de compte sur la console CoreWeave ou si vous préférez la facturation Forge :

Ouvrez les paramètres des clés API Forge. Connectez-vous ou créez un compte à partir de ce même lien.
Copiez votre clé API et définissez-la dans le terminal où vous exécutez le client :
export FORGE_API_KEY="[FORGE-API-KEY]"

Transmettez explicitement la clé via AuthHeaders en Python, ou via createSandboxClient({apiKey: process.env.FORGE_API_KEY}) depuis @coreweave/cwsandbox/wandb en TypeScript. Le guide de démarrage rapide sans serveur fournit des exemples complets. FORGE_API_KEY n’est qu’une variable d’exemple, et non un paramètre que le SDK détecte automatiquement.

Jeton d’accès à l’API CoreWeave

Choisissez CoreWeave pour utiliser la facturation de votre organisation CoreWeave ou pour exécuter des bacs à sable sur son cluster :

Demandez à votre administrateur de créer ou de mettre à jour une politique d’accès qui vous accorde le rôle Sandbox User, nécessaire pour exécuter des bacs à sable. Les administrateurs qui activent les exécuteurs et configurent leurs politiques ont besoin du rôle Sandbox Admin, qui inclut les autorisations d’exécution des bacs à sable. Voir Créer une politique d’accès et Rôles Sandbox.
Sur la page Tokens, cliquez sur Create Token, renseignez les informations du jeton, puis cliquez sur Create.
Copiez le Token Secret et définissez-le dans le terminal où vous exécutez le client :
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

Si vous ne parvenez pas à créer de jeton, demandez à votre administrateur de vous attribuer le rôle Access Token User. Le secret du jeton ne s’affiche qu’une seule fois. Pour plus d’informations, voir Gérer les jetons d’accès à l’API. En Python, sélectionnez AuthStrategy.COREWEAVE_API_KEY. En TypeScript, importez le client depuis @coreweave/cwsandbox/node.

Sélectionner un mode de placement

Python et TypeScript prennent tous deux en charge le placement sans serveur et le placement sur cluster. Le mode sans serveur est utilisé par défaut. La référence PlacementMode répertorie les valeurs de mode prises en charge. Les deux exemples sur cluster lisent CWSANDBOX_API_KEY. Commencez par configurer vos identifiants d’authentification. Suivez ensuite le guide Utiliser vos propres ressources de calcul pour activer un exécuteur, ou le démarrage rapide sans serveur pour installer le client TypeScript. Pour sélectionner explicitement le placement sur cluster :

Python
TypeScript

Utilisez placement_mode="cks". Ajoutez runner_ids pour limiter le placement à certains exécuteurs :

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)

Sans runner_ids, le placement CKS peut utiliser n’importe quel exécuteur éligible de votre organisation. Pour le mode sans serveur, omettez les deux champs ou définissez placement_mode="serverless" sans runner_ids.

Utilisez le point d’entrée CoreWeave et un tableau runnerIds non vide pour sélectionner le placement CKS :

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

const client = createSandboxClientFromEnv();
const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    runnerIds: ["[RUNNER-ID]"],
    resources: { cpu: "1", memory: "1Gi" },
  },
);
console.log(result.stdout);

Omettez runnerIds pour utiliser le placement sans serveur.

Basculer d’un mode à l’autre

Le basculement automatique est disponible dans le client Python. Le client TypeScript permet de choisir l’un ou l’autre mode de placement, mais ne propose pas de basculement automatique. Pour les échecs de placement éligibles, par exemple en l’absence de capacité disponible ou d’exécuteur adapté, le basculement relance une seule fois la création de la sandbox dans l’autre mode. Il ne déplace pas une sandbox en cours d’exécution d’un mode à l’autre. Utilisez un jeton d’accès à l’API CoreWeave associé à une organisation qui dispose à la fois d’un accès sans serveur et d’un exécuteur CKS configuré. Une clé API Forge seule ne donne pas accès à CKS. Pour privilégier CKS et basculer vers le mode sans serveur en cas d’échec, définissez placement_spillover="cks_then_serverless" :

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_spillover="cks_then_serverless",
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)

L’exemple définit le CPU et la mémoire pour les deux tentatives. Chaque mode applique sa propre politique : une requête doit donc respecter la politique du mode dans lequel elle s’exécute. Pour contrôler le basculement, définissez placement_spillover sur l’une des options suivantes :

Option	Première tentative	Basculement	Contraintes
`strict` (par défaut)	Le mode de placement sélectionné	Aucun	Requis lors de la création à partir d’un modèle ou avec `run_from_file()`
`cks_then_serverless`	CKS	Sans serveur	`placement_mode` doit valoir `"cks"` ou être omis
`serverless_then_cks`	Sans serveur	CKS	`placement_mode` doit valoir `"serverless"` ou être omis. Incompatible avec `runner_ids`.

Pour connaître les valeurs de basculement prises en charge, consultez la référence PlacementSpillover. Pour les paramètres de ressources et de délai d’expiration, consultez Configuration du bac à sable.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Placement et basculement des sandbox

Comparer les modes de placement

Choisir et obtenir des identifiants d’authentification

Clé API Forge

Jeton d’accès à l’API CoreWeave

Sélectionner un mode de placement

Basculer d’un mode à l’autre

​Comparer les modes de placement

​Choisir et obtenir des identifiants d’authentification

​Clé API Forge

​Jeton d’accès à l’API CoreWeave

​Sélectionner un mode de placement

​Basculer d’un mode à l’autre

Comparer les modes de placement

Choisir et obtenir des identifiants d’authentification

Clé API Forge

Jeton d’accès à l’API CoreWeave

Sélectionner un mode de placement

Basculer d’un mode à l’autre