Ces exemples utilisent un jeton d’accès à l’API CoreWeave défini dans CWSANDBOX_API_KEY. Pour l’authentification par clé API Forge, voir Premiers pas. Pour les exigences relatives à CKS, voir Modes de placement.
Une connexion directe à une Sandbox achemine les opérations d’exécution, de journalisation et sur les fichiers directement de votre client vers la Sandbox via TLS mutuel (mTLS), sans passer par la passerelle CoreWeave Sandbox. En supprimant ce saut intermédiaire, vous réduisez la latence et augmentez le débit des charges de travail qui transfèrent de grands volumes de données vers et depuis une Sandbox.
Les opérations de cycle de vie et de gestion, comme le démarrage, l’affichage de la liste ou l’arrêt des Sandbox, passent toujours par l’API CoreWeave Sandbox. Une connexion directe ne s’applique qu’aux opérations sur les données d’une Sandbox déjà en cours d’exécution.
Cette page s’adresse aux développeurs qui utilisent le SDK Python cwsandbox pour lancer et gérer des Sandbox. Elle explique comment choisir une politique de transport pour les opérations sur les données, comment le SDK établit une connexion directe et comment vérifier le transport utilisé par une opération.
Aperçu
L’enum DataPlaneMode définit la politique de transport des opérations sur les données. Le SDK utilise AUTO sauf indication contraire de votre part : la plupart des appelants bénéficient ainsi de connexions directes sans modifier leur code.
Définir la politique de transport
Pour définir la politique de transport d’une seule Sandbox, passez data_plane_mode à Sandbox.run(). Pour la définir pour un groupe de Sandbox, passez data_plane_mode à SandboxDefaults.
Établissement d’une connexion directe
Lorsqu’une sandbox est en cours d’exécution et que vous lancez sa première opération sur les données, le SDK génère en mémoire une clé privée P-256 et n’envoie qu’une demande de signature de certificat à l’API CoreWeave Sandboxes. L’API renvoie un certificat limité à cette sandbox, que le SDK utilise pour ouvrir une connexion mTLS directement avec la sandbox.
Deux propriétés de cet échange sont à prendre en compte lorsque vous réfléchissez aux identifiants d’authentification :
- La clé privée ne quitte jamais le processus client. Le SDK transmet une demande de signature de certificat, et non la clé.
- Votre jeton Bearer d’API n’est jamais envoyé au point de terminaison de données de la sandbox. La sandbox authentifie le client uniquement au moyen de son certificat.
Le SDK crée les identifiants d’authentification à la demande : une sandbox qui n’exécute que des appels de cycle de vie n’en demande donc jamais. Le SDK s’appuie sur la date d’expiration du certificat fixée par le serveur, sans imposer de son côté une durée de vie de session plus courte.
Délais et repli
AUTO et DIRECT diffèrent par la durée d’attente et par ce qui se passe lorsque la configuration ne se termine pas à temps.
- En mode
AUTO, l’émission des identifiants d’authentification et la mise en état de préparation du canal se partagent un budget d’une seconde. Une fois ce budget épuisé, l’opération transite par la passerelle et le SDK attend 30 secondes avant de retenter une connexion directe. Le repli est transparent : l’opération aboutit quand même.
- En mode
DIRECT, la configuration de la connexion dispose d’un délai maximal de 10 secondes, sans repli. Si la configuration n’aboutit pas, l’opération lève une erreur.
Réutilisation des connexions
Le SDK maintient, à l’échelle du processus, un pool de canaux directs inactifs limité à 64. Grâce à cette limite, un programme qui conserve un grand nombre d’objets sandbox inactifs ne garde pas un socket ouvert par sandbox.
Un flux actif conserve le canal sur lequel il a démarré. Lorsqu’un canal est marqué comme obsolète, les flux existants s’y terminent progressivement, tandis que les nouveaux appels créent un canal de remplacement.
Vérifier le transport utilisé par une opération
Pour confirmer que la connectivité directe fonctionne depuis votre environnement, exécutez une opération en mode DIRECT. Ce mode ne bascule jamais vers une solution de repli : une opération qui aboutit a donc forcément utilisé le transport direct. Une opération qui ne parvient pas à établir la connexion lève une erreur au lieu de basculer silencieusement sur la passerelle.
Si cette opération génère une erreur alors que le même appel en mode GATEWAY réussit, le point de terminaison de données de la sandbox n’est pas joignable depuis votre réseau. Laissez les appelants en mode AUTO pour qu’ils continuent de fonctionner via la passerelle pendant que vous vérifiez les restrictions de trafic sortant entre votre client et la sandbox.
Voir aussi
Dernière modification le 15 octobre 2026
