Skip to main content
Le client TypeScript prend en charge les montages d’instantanés, les restaurations, les instantanés en cours d’exécution et la gestion des instantanés, mais pas la création d’instantanés à l’arrêt.
Les instantanés du système de fichiers (FSS) permettent à un sandbox d’écrire dans un répertoire de travail local, de capturer ce répertoire dans le stockage d’objets sous forme d’instantané immuable, puis de le restaurer ultérieurement dans de nouveaux sandboxes. Utilisez les FSS pour suspendre et reprendre le système de fichiers d’un sandbox d’un run à l’autre, ou pour créer une branche à partir d’un instantané dans plusieurs sandboxes qui évoluent ensuite indépendamment les uns des autres.

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section indique CoreWeave Kubernetes Service (CKS). Choisissez l’identifiant d’authentification du compte propriétaire de vos Sandbox. Consultez Choisir et obtenir des identifiants pour obtenir une clé ou un jeton. Enregistrez la configuration correspondant à votre langage dans le même répertoire que les scripts que vous exécutez depuis cette page. Les exemples Python importent AUTH depuis sandbox_auth.py. Les exemples TypeScript importent client depuis sandbox-client.mts. Ces fichiers sélectionnent l’authentification sans stocker votre identifiant d’authentification. Pour Python, utilisez un environnement virtuel actif. Pour TypeScript, installez d’abord le client avec npm install @coreweave/cwsandbox@1.0.0.
Utilisez votre clé API Forge avec l’intégration wandb du SDK. Remplacez [WANDB-API-KEY] par votre clé API :
sandbox_auth.py
Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création du Sandbox ou dans SandboxDefaults. En TypeScript, choisissez le jeton CoreWeave et définissez un tableau runnerIds non vide pour sélectionner CKS. La création d’une session Python avec auth=AUTH authentifie également les Sandbox qui lui appartiennent. Conservez le même identifiant d’authentification pour vous reconnecter à vos Sandbox, les lister ou les nettoyer. Pour les exemples d’API HTTP, exécutez les commandes Bash de l’onglet correspondant à votre identifiant d’authentification dans le même shell que les requêtes. Le tableau sandbox_headers fournit l’en-tête d’authentification sélectionné. Les exemples de création via HTTP utilisent un placement sans serveur.

Fonctionnement

Une Sandbox avec FSS monte un système de fichiers temporaire accessible en écriture à l’emplacement de votre choix. L’exécuteur s’appuie sur un EmptyDir pour ce montage, et non sur un montage direct du stockage d’objets. Les opérations d’instantané et de restauration copient une archive tar entre ce système de fichiers local et un bucket de stockage d’objets limité à l’organisation. Chaque instantané est une ressource FileSystemSnapshot identifiée par un fileSystemSnapshotId attribué par le serveur. Les instantanés se caractérisent par trois propriétés :
  • Immuable : la création d’un instantané écrit une seule archive. La restauration d’un instantané ne modifie jamais l’instantané source ; une restauration ultérieure retrouve donc toujours les octets d’origine.
  • Limité à l’organisation : vous ne pouvez restaurer que les instantanés créés dans votre propre organisation. Un membre de votre équipe disposant d’un accès aux Sandbox dans la même organisation peut restaurer votre instantané avec ses propres identifiants d’authentification. Un ID d’instantané provenant d’une autre organisation est considéré comme introuvable.
  • Cycle de vie indépendant : les instantanés sont gérés séparément des Sandbox. La suppression d’une Sandbox ne supprime pas ses instantanés, et la suppression d’un instantané n’a aucune incidence sur les Sandbox déjà lancées à partir de celui-ci.
Par défaut, CoreWeave provisionne et gère le bucket de stockage d’objets qui contient vos instantanés. Pour stocker plutôt vos instantanés dans un bucket que vous possédez et contrôlez, consultez Utilisez votre propre bucket, qui détaille les prérequis relatifs au compte CoreWeave et au bucket.

Démarrer un sandbox avec un montage d’instantané

Un sandbox peut démarrer à partir de l’une de ces deux sources de système de fichiers : un système de fichiers temporaire, neuf et vide, ou la restauration d’un instantané existant.

Système de fichiers temporaire vierge

Un système de fichiers temporaire vierge est vide au démarrage et peut faire l’objet d’un instantané par la suite. Utilisez-le pour les flux de travail qui nécessitent un état local accessible en écriture pendant l’exécution.

Restaurer à partir d’un instantané

Une restauration initialise le système de fichiers à partir d’un instantané existant. Indiquez l’ID de l’instantané dans la source d’instantané du point de montage.
Un instantané doit être à l’état READY pour pouvoir être restauré. La restauration d’un instantané encore à l’état CREATING échoue. Consultez Statut et échecs des instantanés.

Prévoir le temps de restauration

Lors de la restauration d’un instantané, son archive est copiée puis extraite avant que la sandbox puisse exécuter votre application. La restauration d’instantanés de modèles volumineux peut prendre plusieurs minutes. Le temps de démarrage dépend des facteurs suivants :
  • Taille de l’archive
  • Nombre de fichiers
  • CPU disponible
  • Stockage local
  • Débit réseau
  • Opérations de démarrage de l’image
La capacité de montage demandée ne suffit pas, à elle seule, à prédire le temps de restauration. Pour choisir un délai de démarrage, mesurez des lancements à froid avec votre image, votre instantané et vos demandes de ressources. Le statut CREATING ne permet pas, à lui seul, de distinguer l’attente de l’ordonnancement de la restauration des fichiers. Avant de supprimer un lancement lent, vérifiez le champ status_reason de la sandbox et conservez son ID pour l’assistance. Un délai fixe permet de borner votre attente, mais le temps écoulé ne suffit pas à établir qu’une restauration a échoué.

Prendre un instantané

Vous pouvez capturer un instantané de deux façons : à l’arrêt, lorsqu’une sandbox s’éteint, ou en cours d’exécution, depuis une sandbox active.

Instantané à l’arrêt

Pour conserver le système de fichiers d’une sandbox lors de son arrêt, arrêtez-la en activant l’instantané à l’arrêt. C’est la méthode à suivre pour suspendre puis reprendre une sandbox : arrêtez-la avec un instantané, puis démarrez ultérieurement une nouvelle sandbox qui le restaure.

Instantané en cours d’exécution

Un instantané en cours d’exécution capture une sandbox active sans l’arrêter. La sandbox continue de s’exécuter pendant et après la capture. La capture parcourt le système de fichiers actif et n’est pas atomique : les écritures effectuées pendant la capture risquent donc de ne pas être capturées de manière cohérente. Si vous avez besoin d’un état cohérent, suspendez les écritures de l’application pendant la capture ou créez un point de contrôle applicatif au préalable.
Par défaut, snapshot() attend que l’instantané soit READY, puis renvoie son ID.

Créer une branche à partir d’un instantané

Un même instantané peut être restauré dans plusieurs sandbox. Comme chaque instantané est immuable, les sandbox restaurées démarrent à partir d’octets identiques, puis divergent au fil de leurs écritures.
  1. Créez un instantané READY, soit avec un instantané à l’arrêt, soit avec un instantané en cours d’exécution.
  2. Démarrez la sandbox A en définissant fileSystemSnapshotId sur cet instantané.
  3. Démarrez la sandbox B avec le même fileSystemSnapshotId.
  4. Les écritures effectuées dans la sandbox A et dans la sandbox B divergent indépendamment les unes des autres. L’instantané source n’est pas modifié : une restauration ultérieure à partir du même ID retrouve donc l’instantané original, et non les écritures de l’une ou l’autre branche.

Gérer les instantanés

Listez, récupérez et supprimez les instantanés indépendamment des Sandbox qui les ont créés.
list_snapshots(), get_snapshot() et delete_snapshot() acceptent également un objet AuthHeaders via le paramètre auth.

Statut des instantanés et échecs

Les instantanés sont créés de manière asynchrone. Une requête d’instantané peut réussir et renvoyer un fileSystemSnapshotId alors que l’archive est encore en cours d’écriture, puis l’instantané peut échouer par la suite. Cela se produit le plus souvent lorsque waitForReady vaut false, ou lorsque le délai d’expiration côté client est atteint alors que l’exécuteur est encore en train d’archiver. Pour suivre la progression via l’API HTTP, récupérez l’instantané et consultez les champs suivants :
  • status : l’état du cycle de vie. Les valeurs finales sont FILE_SYSTEM_SNAPSHOT_STATUS_READY et FILE_SYSTEM_SNAPSHOT_STATUS_FAILED.
  • statusReason : renseigné lorsque status vaut FILE_SYSTEM_SNAPSHOT_STATUS_FAILED, pour indiquer la cause de l’échec.
En TypeScript, consultez les champs state et stateReason de l’enregistrement de l’instantané. Les valeurs d’état correspondantes sont "ready" et "failed". Interrogez GetFileSystemSnapshot jusqu’à ce que l’instantané soit prêt avant de le restaurer. Les méthodes snapshot() et get_snapshot() du client Python se chargent de cette interrogation pour vous lorsque vous attendez le résultat. La méthode snapshot() du client TypeScript attend que state vaille "ready" et lève une exception si l’instantané échoue.

Récupérer après l’échec d’une requête d’instantané

Pendant la récupération après l’échec d’un instantané en cours d’exécution, laissez la sandbox source en fonctionnement. L’échec d’un appel de procédure à distance (RPC) d’instantané ne supprime pas en soi la sandbox ni son point de montage. En revanche, si vous quittez un gestionnaire de contexte de sandbox Python ou exécutez du code de démontage, la sandbox peut s’arrêter. Les données qui ne figurent pas encore dans un instantané prêt peuvent alors être perdues. Traitez l’échec avant que ce nettoyage ne s’exécute. Lors de la première utilisation, le provisionnement du bucket peut renvoyer CWSANDBOX_FSS_BUCKET_PROVISIONING. Le client Python effectue automatiquement de nouvelles tentatives en cas d’échecs transitoires des RPC d’instantané, dans la limite d’un budget défini. Si le provisionnement dure plus longtemps que ce budget, réessayez en espaçant progressivement les tentatives, tout en conservant la sandbox source. Lorsque vous relancez la même requête après un échec de transport ambigu, réutilisez un request_id explicite afin que le serveur puisse la dédupliquer. Si un ID d’instantané est disponible après l’expiration du délai, vérifiez cet instantané avant de demander une nouvelle archive. Un instantané passé à l’état FAILED nécessite une nouvelle requête pour capturer à nouveau les données. Avec le client Python 1.19.6, les échecs transitoires d’instantané peuvent lever SandboxUnavailableError, tandis que les autres échecs d’instantané lèvent SandboxSnapshotError. Pour préserver une compilation, gérez ces deux exceptions et utilisez le champ reason de l’erreur pour déterminer s’il convient de réessayer. En cas d’échec lié au quota ou à la configuration, ne réessayez pas sans en avoir d’abord corrigé la cause. Le tableau suivant répertorie les causes d’échec courantes et la marche à suivre pour chacune. Si un exécuteur termine le téléversement de l’archive sans parvenir à enregistrer le résultat, la ligne de l’instantané peut passer à l’état FAILED alors même qu’un objet existe dans le bucket. Dans ce cas, relancez l’instantané. En cas d’échec asynchrone, la plateforme émet également un événement sandbox.file_system_snapshot.async_fail, ce qui permet aux systèmes de notification en aval de réagir aux instantanés qui échouent après le retour de l’appel initial.

Limitations

La version 1 de FSS fournit un stockage local temporaire adossé à des instantanés. Il ne s’agit pas d’un système de fichiers partagé, et il ne permet pas de montages actifs accessibles en écriture par plusieurs clients. Pendant leur exécution, les bacs à sable ne peuvent ni lire ni écrire dans les systèmes de fichiers des autres bacs à sable. Ils ne partagent leur état que par la création et la restauration d’instantanés.

Exemple avec le SDK

Pour un exemple Python complet et exécutable qui démarre une sandbox, réalise un instantané en cours d’exécution, en crée une branche, capture un instantané à l’arrêt et gère les instantanés, consultez file_system_snapshots.py dans le dépôt cwsandbox-client. Pour TypeScript, le fichier file-system-snapshots.ts du dépôt cwsandbox-js réalise un instantané en cours d’exécution, le restaure et gère les instantanés.
Dernière modification le 4 novembre 2026