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, qui est aussi celui facturé pour son utilisation. Les clés API Forge prennent en charge les sandboxes sans serveur. Les jetons d’accès à l’API CoreWeave prennent en charge à la fois les sandboxes sans serveur et ceux exécutés sur un cluster. La variable d’environnement et la stratégie d’authentification identifient l’identifiant d’authentification, indépendamment du mode de placement :

Identifiant d’authentification	Variable d’environnement	Stratégie Python	Placement
Clé API Forge (authentification W&B)	`WANDB_API_KEY`	`AuthStrategy.WANDB`	Sans serveur
Jeton d’accès à l’API CoreWeave	`CWSANDBOX_API_KEY`	`AuthStrategy.COREWEAVE_API_KEY`	Sans serveur ou CKS

Choisissez explicitement un identifiant d’authentification, même si les deux variables sont définies. Utilisez le même compte pour créer un sandbox, vous y reconnecter, le lister et l’arrêter.

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

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 via ce même lien.
Copiez votre clé API et définissez-la dans le terminal où vous exécutez le client :
export WANDB_API_KEY="[WANDB-API-KEY]"

En Python, installez cwsandbox[wandb] et sélectionnez auth=AuthStrategy.WANDB. En TypeScript, utilisez le point d’entrée @coreweave/cwsandbox/wandb. Définir uniquement WANDB_API_KEY ne suffit pas à modifier la stratégie par défaut (CoreWeave) du client Python. Le démarrage rapide sans serveur contient des exemples complets.

Choisissez CoreWeave pour utiliser la facturation de votre organisation CoreWeave ou pour exécuter des sandboxes 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 sandboxes. 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 sandboxes. 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

Sélectionner un mode de placement

Basculer d’un mode à l’autre

​Comparer les modes de placement

​Choisir et obtenir des identifiants d’authentification

​Sélectionner un mode de placement

​Basculer d’un mode à l’autre

Comparer les modes de placement

Choisir et obtenir des identifiants d’authentification

Sélectionner un mode de placement

Basculer d’un mode à l’autre