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

# Créer une sandbox à partir d’un fichier Compose

> Démarrez une sandbox multi-conteneur en téléversant un fichier Docker Compose vers l’API des sandboxes.

`POST /v1/sandboxes:createFromFile` démarre une sandbox à partir d’un fichier téléversé. Vous envoyez un type de fichier et le contenu binaire du fichier ; la passerelle des sandboxes convertit alors le document en spécification de sandbox et suit le même processus de création que `POST /v1/sandboxes`.

Docker Compose (`SANDBOX_FILE_TYPE_COMPOSE`) est le seul type de fichier accepté. Chaque service du fichier devient un conteneur au sein d’une même sandbox, et le service que vous désignez devient le conteneur principal de la sandbox. La passerelle ne stocke pas le contenu du fichier. `GET /v1/sandboxes/{sandboxId}` renvoie la spécification convertie.

Cette fonctionnalité n’offre pas une équivalence complète avec Docker Compose. Avant d’importer un projet existant, consultez [Prise en charge de Compose](#compose-support).

<h2 id="before-you-begin">
  Avant de commencer
</h2>

Les exemples suivants utilisent une clé API Forge. Voir [Premiers pas](/fr/products/sandboxes/get-started). Transmettez la clé dans l’en-tête `x-wandb-api-key`. Pour créer la sandbox dans une entity Forge autre que votre entity par défaut, transmettez également l’en-tête `x-entity-id`.

```bash theme={"system"}
export FORGE_API_KEY="[FORGE-API-KEY]"
```

Vous pouvez également utiliser un jeton d’accès à l’API CoreWeave avec l’action `SANDBOX_USER`, y compris pour le placement sur CKS. Suivez les instructions de la section [Choisir et obtenir des identifiants d’authentification](/fr/products/sandboxes/placement#choose-and-get-credentials), puis définissez le jeton :

```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
```

Pour chaque requête de ce guide, remplacez `-H "x-wandb-api-key: $FORGE_API_KEY"` par `-H "Authorization: Bearer $CWSANDBOX_API_KEY"` afin d’utiliser ce jeton. L’authentification et le format des erreurs sont les mêmes que pour le reste de l’API. Voir [Aperçu de l’API](/fr/products/sandboxes/reference/control-plane-api).

<h2 id="request-fields">
  Champs de la requête
</h2>

| Champ | Requis | Description |
| - | - | - |
| `type` | Oui | Type de document. Utilisez `SANDBOX_FILE_TYPE_COMPOSE`. |
| `contents` | Oui | Octets du fichier, encodés en base64 dans le JSON. UTF-8, 256 Kio maximum. |
| `primaryService` | Oui | Service qui devient le service principal de la sandbox. Doit désigner un service défini dans `contents`. Aucune valeur par défaut. |
| `imageOverrides` | Non | Références d’image par service. Les clés doivent désigner des services définis dans le fichier. Utilisez ce champ pour fournir une image récupérable à un service qui nécessiterait sinon une compilation. |
| `defaultResources` | Conditionnel | CPU et mémoire copiés sur chaque service qui ne définit pas `deploy.resources`. S’applique par conteneur, et non comme un budget de projet. Toute valeur GPU spécifiée ici est rejetée. Requis lorsque le fichier contient plusieurs services et qu’au moins l’un d’eux ne définit pas `deploy.resources`. |

La requête accepte également `mode`, `maxLifetimeSeconds`, `tags`, `network`, `objectStorageAccess`, `annotations`, `runnerIds` et `requestId`, avec la même signification que pour `POST /v1/sandboxes`. `networkIds` renvoie `UNIMPLEMENTED`.

Pour un placement sur CKS, utilisez un jeton d’accès à l’API CoreWeave et configurez les champs de placement comme décrit dans [Placement et débordement des sandboxes](/fr/products/sandboxes/placement). Pour les prérequis liés au stockage d’objets, consultez [Accorder aux sandboxes l’accès à AI Object Storage](/fr/products/sandboxes/operations/object-storage-access).

Cette liste de champs est exhaustive. Les volumes, le type d’instance, la classe de runtime, les identifiants d’authentification pour la récupération d’images et les services publiés ne sont pas disponibles sur ce point de terminaison. Utilisez `POST /v1/sandboxes` si vous en avez besoin.

<h2 id="create-the-sandbox">
  Créer la sandbox
</h2>

Écrivez un fichier Compose :

```bash title="Write compose.yaml" theme={"system"}
cat > compose.yaml <<'EOF'
services:
  helper:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    expose: ["8080"]
    healthcheck:
      test: ["CMD", "true"]
      interval: 1s
      timeout: 1s
      retries: 3
  main:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    environment:
      HELPER_HOST: helper
    depends_on:
      helper:
        condition: service_healthy
EOF
```

Envoyez-le via une requête POST, avec `contents` encodé en base64 :

```bash title="Create a sandbox from compose.yaml" theme={"system"}
jq -n --rawfile yaml compose.yaml '{
  type: "SANDBOX_FILE_TYPE_COMPOSE",
  contents: ($yaml | @base64),
  primaryService: "main",
  defaultResources: { requests: { cpu: "100m", memory: "128Mi" } },
  maxLifetimeSeconds: 3600,
  tags: ["from-file"]
}' | curl -sS -X POST https://api.cwsandbox.com/v1/sandboxes:createFromFile \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @-
```

La réponse renvoie une sandbox à l’état `STATE_CREATING`. Interrogez-la régulièrement à l’aide de son `sandboxId` jusqu’à ce qu’elle atteigne l’état `STATE_RUNNING` ou un état terminal :

```bash title="Poll the sandbox" theme={"system"}
export SANDBOX_ID="[SANDBOX-ID]"

curl -sS "https://api.cwsandbox.com/v1/sandboxes/$SANDBOX_ID" \
  -H "x-wandb-api-key: $FORGE_API_KEY"
```

La spécification renvoyée comporte deux conteneurs : `main`, marqué comme principal, et `HELPER_HOST`, toujours défini sur `helper`. Dans le sandbox, `helper` est résolu en `127.0.0.1`.

Pour relancer une création sans risque, envoyez `requestId`. Un même `requestId` associé aux mêmes entrées déclarées renvoie le sandbox existant. Un même `requestId` associé à des octets différents, y compris lorsque la modification ne porte que sur des caractères d’espacement, renvoie `ALREADY_EXISTS` avec le motif `CWSANDBOX_REQUEST_ID_CONFLICT`.

<h2 id="compose-support">
  Prise en charge de Compose
</h2>

Tous les services partagent un même pod et un même namespace réseau. Les noms de service sont résolus en `127.0.0.1`, si bien que des valeurs telles que `HELPER_HOST: helper` et `API_BASE: http://main:8080` fonctionnent sans qu’il soit nécessaire de réécrire le fichier. La sandbox ne dispose ni d’adresses IP par service, ni de réseaux bridge, ni de répliques.

Les comportements suivants diffèrent de ceux de Docker Compose :

* **Le démarrage est séquentiel.** Les services non principaux démarrent les uns après les autres, avant le service principal. Dimensionnez `maxLifetimeSeconds` en conséquence. Si un service ne devient jamais prêt, la sandbox reste dans l’état `STATE_CREATING`.
* **`RUNNING` ne suit que le service principal.** Le plantage d’un service auxiliaire après son démarrage ne fait pas échouer la sandbox.
* **`healthcheck` devient une sonde de démarrage de type exec uniquement.** `test` doit être une chaîne, `CMD`, `CMD-SHELL` ou `NONE`, et les durées doivent être exprimées en secondes entières. Lorsque la sonde a épuisé ses tentatives, le conteneur est arrêté au lieu d’être marqué comme défaillant.
* **Les ports restent internes au pod.** `expose` et `ports` déclarent des ports d’écoute, mais rien n’est publié à l’extérieur.
* **Les images doivent pouvoir être récupérées.** Chaque service doit avoir une clé `image:` dans le fichier ou une entrée dans `imageOverrides`. Un service qui requiert encore `build:` renvoie `UNIMPLEMENTED`.
* **`command` et `entrypoint` suivent les formes shell et exec de Docker.** Omettez-les pour utiliser les valeurs par défaut de l’image. Les valeurs explicites `null` et `[]` sont rejetées.
* **Les GPU sont réservés au service principal**, via `deploy.resources.reservations.devices` avec la capacité `gpu` et un nombre entier positif.
* **Les noms doivent être des libellés DNS-1123** (`my-app`, et non `My_App`) et ne peuvent pas utiliser les préfixes réservés `cw-object-store-agent`, `cw-object-store-agent-restore` ou `dns-egress`.

<h3 id="unsupported-keys">
  Clés non prises en charge
</h3>

Le document doit être autonome : la passerelle ne lit pas votre disque et ne développe pas les variables de votre environnement. Les clés non reconnues ne sont pas ignorées, mais rejetées avec le chemin du champ en cause.

| Rejeté | Notes |
| - | - |
| Interpolation `$VAR` et `${VAR}` | Écrivez `$$` pour obtenir un `$` littéral. |
| `include`, `extends`, `env_file` | Uniquement `environment` ou `env` en ligne. Les clés sans valeur et les valeurs `null` sont également rejetées. |
| `volumes`, `tmpfs`, `configs`, `secrets`, montages de liaison | Les projets qui utilisent des volumes nommés ne peuvent pas être importés. |
| `restart`, `logging`, `profiles`, `stdin_open`, `tty`, `scale` | Non implémentés sur ce runtime. |
| `network_mode`, `pid`, `ipc`, `extra_hosts`, réseaux nommés | Un pod, un namespace. |
| Mappages de ports hôte-conteneur, adresses de liaison, plages de ports, protocoles autres que TCP, ports en double entre services | Un seul port d’écoute TCP par entrée, unique dans toute la sandbox. |
| `depends_on: service_completed_successfully`, ou tout `depends_on` ciblant le service principal | `service_healthy` et `service_started` sont pris en charge entre services non principaux. |
| Notations de mémoire Compose (`512m`, `2g`, `512mb`) | Utilisez des quantités Kubernetes telles que `512Mi` ou `1Gi`. |
| Valeurs `user` nommées (`nobody`) | Utilisez un UID numérique. |

La passerelle ignore les clés `version`, `name` du projet, `labels` et les clés d’extension `x-*`. Ne comptez pas sur la transmission des `labels` à la sandbox.

<h2 id="common-errors">
  Erreurs courantes
</h2>

Les violations de champ sont renvoyées sous forme de détails `BadRequest` qui indiquent le chemin et la limite concernés. Elles ne reprennent pas le contenu de votre document.

| Situation | Code et motif | Champ |
| - | - | - |
| `type` omis | `INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST` | `type` |
| Type autre que Compose | `UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED` | `type` |
| `primaryService` omis ou inconnu | `INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST` | `primary_service` |
| Service sans `image:` ni `build:` | `INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST` | `contents.services.<name>` |
| Service qui requiert encore `build:` | `UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED` | `contents.services.<name>.build` |
| Fichier de plus de 256 Kio, ou ne constituant pas un document YAML UTF-8 unique | `INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST` | `contents` |
| Clé Compose non prise en charge | `INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST` | Le chemin de la clé |
| Même `requestId`, octets différents | `ALREADY_EXISTS`, `CWSANDBOX_REQUEST_ID_CONFLICT` | Aucun |

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

* [Premiers pas](/fr/products/sandboxes/get-started) : créez votre première sandbox à partir d’une spécification.
* [Aperçu de l’API](/fr/products/sandboxes/reference/control-plane-api) : authentification, gestion des versions et des erreurs.
* [Variables d’environnement des sandboxes](/fr/products/sandboxes/environment-variables) : ce que la plateforme injecte dans chaque conteneur.