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

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. Ce guide porte sur les fichiers Compose qui utilisent des images précompilées et récupérables. Avant d’importer un projet existant, consultez Prise en charge de Compose.

Avant de commencer

Choisissez un identifiant d’authentification dans Choisir et obtenir des identifiants. Exécutez les commandes de l’un des onglets dans Bash, puis exécutez les requêtes dans le même shell. Pour un placement sans serveur, utilisez l’identifiant d’authentification d’un compte ayant accès aux Sandbox sans serveur. Le placement CoreWeave Kubernetes Service (CKS) nécessite un jeton CoreWeave doté du rôle Sandbox User ainsi qu’un exécuteur configuré dans la même organisation.

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

Remplacez [WANDB-API-KEY] par votre clé API :

export WANDB_API_KEY="[WANDB-API-KEY]"
sandbox_headers=(-H "x-wandb-api-key: $WANDB_API_KEY")

Pour utiliser une autre équipe Forge que votre équipe par défaut, remplacez [WANDB-ENTITY] par le nom de l’équipe et ajoutez -H "x-entity-id: [WANDB-ENTITY]" au tableau.

Remplacez [API-ACCESS-TOKEN] par votre jeton :

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
sandbox_headers=(-H "Authorization: Bearer $CWSANDBOX_API_KEY")

Les requêtes de la section Créer le Sandbox utilisent l’API runtime des Sandbox, à l’adresse https://api.cwsandbox.com, avec un placement sans serveur et l’en-tête d’authentification choisi. L’API d’administration des exécuteurs utilise https://api.coreweave.com et nécessite un jeton CoreWeave doté du rôle Sandbox Admin.

Champs de la requête

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, choisissez l’onglet du jeton CoreWeave et activez un exécuteur. Dans l’objet jq de l’exemple de création, définissez mode sur "SANDBOX_MODE_CKS". Pour cibler un exécuteur précis, ajoutez également runnerIds: ["[RUNNER-ID]"], en remplaçant la valeur de substitution par son ID. Pour les prérequis liés au stockage d’objets, consultez Accorder aux Sandbox l’accès à AI Object Storage. 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.

Créer le bac à sable

Écrivez un fichier Compose :

Write compose.yaml

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 :

Create a sandbox from compose.yaml

jq -n --rawfile yaml compose.yaml '{
  type: "SANDBOX_FILE_TYPE_COMPOSE",
  contents: ($yaml | @base64),
  primaryService: "main",
  mode: "SANDBOX_MODE_SERVERLESS",
  defaultResources: { requests: { cpu: "100m", memory: "128Mi" } },
  maxLifetimeSeconds: 3600,
  tags: ["from-file"]
}' | curl -sS -X POST https://api.cwsandbox.com/v1/sandboxes:createFromFile \
  "${sandbox_headers[@]}" \
  -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 :

Poll the sandbox

export SANDBOX_ID="[SANDBOX-ID]"

curl -sS "https://api.cwsandbox.com/v1/sandboxes/$SANDBOX_ID" \
  "${sandbox_headers[@]}"

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.

Créer un sandbox depuis TypeScript

Le kit de développement logiciel (SDK) TypeScript 1.0.0 prend en charge Compose via runFromFile() et withSandboxFromFile(). Effectuez d’abord la configuration du client TypeScript, puis enregistrez le fichier sandbox-client.mts dans le même répertoire que ce script. Utilisez le fichier compose.yaml de la section Créer le sandbox. withSandboxFromFile() attend que le sandbox soit prêt, exécute la fonction de rappel, puis arrête le sandbox dès que la fonction de rappel a renvoyé une valeur ou levé une exception :

compose.mts

import { client } from "./sandbox-client.mjs";

await client.withSandboxFromFile(
  "./compose.yaml",
  async (sandbox) => {
    const result = await sandbox.commands.run(["echo", "Compose sandbox ready"]);
    console.log(result.stdout);
  },
  {
    primaryService: "main",
    defaultResources: { cpu: "100m", memory: "128Mi" },
    maxLifetimeSeconds: 3600,
  },
);

Depuis le répertoire contenant ces fichiers, exécutez le script :

npx --yes --package=tsx tsx compose.mts

Le script affiche Compose sandbox ready et arrête le sandbox. Un argument de type string est toujours un chemin de fichier. Pour fournir du YAML en ligne, transmettez des octets UTF-8 avec new TextEncoder().encode(yaml). Le SDK envoie les octets tels quels, sans les reformater. Veillez à ce que le fichier ne dépasse pas la limite de 256 Kio imposée par l’API. Dans la version 1.0.0, primaryService est requis et doit désigner un service défini dans le fichier. defaultResources définit le CPU et la mémoire de chaque service, et non de l’ensemble du projet. Il ne prend pas en charge les ressources GPU. Utilisez imageOverrides pour fournir des images récupérables aux services qui nécessiteraient autrement une compilation. Les restrictions décrites dans la section Prise en charge de Compose s’appliquent également au SDK. Pour gérer manuellement le cycle de vie, utilisez runFromFile(), qui renvoie un handle de sandbox. Arrêtez-le dans un bloc finally. Pour les signatures des deux méthodes, voir SandboxClient. Pour les options prises en charge, voir SandboxRunFromFileOptions.

Prise en charge de Compose

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.
Utilisez des images précompilées. Fournissez pour chaque service une image pouvant être récupérée, via 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.

Clés non prises en charge

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` peuvent cibler des services non principaux. `service_healthy` nécessite qu’un healthcheck effectif soit défini sur le service cible.
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.

Erreurs courantes

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

Voir aussi

Premiers pas : créez votre première Sandbox à partir d’une spécification.
API d’administration des exécuteurs : gérez les exécuteurs avec un jeton d’accès à l’API CoreWeave et le rôle Sandbox Admin.
Variables d’environnement des Sandbox : ce que la plateforme injecte dans chaque conteneur.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

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

Avant de commencer

Champs de la requête

Créer le bac à sable

Créer un sandbox depuis TypeScript

Prise en charge de Compose

Clés non prises en charge

Erreurs courantes

Voir aussi

​Avant de commencer

​Champs de la requête

​Créer le bac à sable

​Créer un sandbox depuis TypeScript

​Prise en charge de Compose

​Clés non prises en charge

​Erreurs courantes

​Voir aussi

Avant de commencer

Champs de la requête

Créer le bac à sable

Créer un sandbox depuis TypeScript

Prise en charge de Compose

Clés non prises en charge

Erreurs courantes

Voir aussi