> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connexions directes aux Sandbox

> Acheminez les opérations d’exécution, de journalisation et sur les fichiers via une connexion mTLS directe plutôt que par la passerelle.

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](/fr/products/sandboxes/get-started). Pour les exigences relatives à CKS, voir [Modes de placement](/fr/products/sandboxes/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.

<h2 id="overview">
  Aperçu
</h2>

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.

| Mode | Comportement | Quand l’utiliser |
| - | - | - |
| `AUTO` | Privilégie une connexion mTLS directe et bascule de manière transparente vers la passerelle lorsque l’accès direct n’est pas disponible. | Valeur par défaut. Utilisez-la, sauf si vous devez imposer un transport précis. |
| `DIRECT` | Exige la connexion mTLS directe et lève une erreur si celle-ci ne peut pas être établie. | Pour vérifier que la connectivité directe fonctionne dans votre environnement. |
| `GATEWAY` | Achemine toujours les opérations sur les données via la passerelle. | Solution de retour arrière déterministe lorsque vous devez écarter le transport direct. |

<h2 id="set-the-transport-policy">
  Définir la politique de transport
</h2>

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

```python theme={"system"}
from cwsandbox import DataPlaneMode, Sandbox, SandboxDefaults

# AUTO est la valeur par défaut : privilégie le chemin direct, avec repli sur la passerelle.
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
    print(result.stdout)

# Exiger le chemin direct. Utile pour valider la connectivité.
with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    print(sandbox.read_file("/etc/hostname").result().decode())

# Forcer le passage par la passerelle pour chaque sandbox utilisant ces valeurs par défaut.
defaults = SandboxDefaults(data_plane_mode=DataPlaneMode.GATEWAY)
with Sandbox.run(defaults=defaults) as sandbox:
    print(sandbox.exec(["echo", "gateway"]).result().stdout)
```

<h2 id="how-a-direct-connection-is-established">
  Établissement d’une connexion directe
</h2>

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.

<h2 id="timing-and-fallback">
  Délais et repli
</h2>

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

<h2 id="connection-reuse">
  Réutilisation des connexions
</h2>

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.

<h2 id="verify-which-transport-an-operation-used">
  Vérifier le transport utilisé par une opération
</h2>

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.

```python theme={"system"}
from cwsandbox import DataPlaneMode, Sandbox

with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    result = sandbox.exec(["echo", "direct"]).result()
    print(result.stdout)
```

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.

<h2 id="see-also">
  Voir aussi
</h2>

* [Architecture des bacs à sable](/fr/products/sandboxes/architecture) : comment s’articulent le plan de contrôle, la passerelle et les exécuteurs.

* [Exécution](/fr/products/sandboxes/client/guides/execution) : lancer des commandes dans une sandbox.

* [Opérations sur les fichiers](/fr/products/sandboxes/client/guides/file-operations) : lire et écrire des fichiers dans une sandbox.

* [Configuration du bac à sable](/fr/products/sandboxes/client/guides/sandbox-configuration) : les autres options que vous pouvez définir via `SandboxDefaults` et `Sandbox.run()`.