Compose ファイルからサンドボックスを作成する

POST /v1/sandboxes:createFromFile は、アップロードされたファイルからサンドボックスを起動します。ファイルタイプとファイルのバイト列を送信すると、サンドボックスのゲートウェイがドキュメントをサンドボックスの spec に変換し、POST /v1/sandboxes と同じ作成処理を実行します。受け付けるファイルタイプは Docker Compose (SANDBOX_FILE_TYPE_COMPOSE) のみです。ファイル内の各サービスは、単一のサンドボックス内のコンテナーになり、指定した 1 つのサービスがサンドボックスのプライマリになります。ゲートウェイはファイルのバイト列を保存しません。GET /v1/sandboxes/{sandboxId} は変換された spec を返します。このガイドでは、プル可能なビルド済みイメージを使用する Compose ファイルについて説明します。既存の project をインポートする前に、Compose のサポートをお読みください。

始める前に

認証情報の選択と取得から認証情報を選択します。いずれか 1 つのタブのコマンドを Bash で実行し、続けて同じシェルでリクエストを実行してください。サーバーレス配置の場合は、サーバーレスサンドボックスへのアクセス権を持つアカウントの認証情報を使用します。CoreWeave Kubernetes Service (CKS) 配置を使用するには、Sandbox User ロールを持つ CoreWeave トークンと、同じ組織内に設定済みのランナーが必要です。

Forge APIキー
CoreWeave API アクセストークン

[WANDB-API-KEY] をお使いの APIキーに置き換えます。

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

デフォルト以外の Forge チームを使用する場合は、[WANDB-ENTITY] をチーム名に置き換え、配列に -H "x-entity-id: [WANDB-ENTITY]" を追加します。

[API-ACCESS-TOKEN] をお使いのトークンに置き換えます。

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

サンドボックスを作成するのリクエストでは、サーバーレス配置と選択した認証ヘッダーを使用して、https://api.cwsandbox.com のサンドボックスランタイム API を呼び出します。ランナー管理 API のエンドポイントは https://api.coreweave.com で、Sandbox Admin ロールを持つ CoreWeave トークンが必要です。

リクエストフィールド

フィールド	必須	説明
`type`	はい	ドキュメントの種類です。`SANDBOX_FILE_TYPE_COMPOSE` を使用します。
`contents`	はい	JSON 内で base64 エンコードされたファイルのバイト列です。UTF-8、最大 256 KiB です。
`primaryService`	はい	サンドボックスのプライマリとなるサービスです。`contents` 内のサービス名を指定する必要があります。デフォルトはありません。
`imageOverrides`	いいえ	サービスごとのイメージ参照です。キーにはファイル内のサービス名を指定する必要があります。本来ビルドが必要なサービスに、プル可能なイメージを指定するために使用します。
`defaultResources`	条件付き	`deploy.resources` を省略した各サービスにコピーされる CPU とメモリです。コンテナーごとの設定であり、project の予算ではありません。ここで GPU を指定すると拒否されます。ファイルに複数のサービスがあり、いずれかのサービスで `deploy.resources` が省略されている場合は必須です。

リクエストでは、mode、maxLifetimeSeconds、tags、network、objectStorageAccess、annotations、runnerIds、requestId も受け入れます。意味は POST /v1/sandboxes と同じです。networkIds は UNIMPLEMENTED を返します。 CKS に配置する場合は、CoreWeave トークンのタブを選択し、ランナーを有効にします。次に、作成例の jq オブジェクト内の mode を "SANDBOX_MODE_CKS" に変更します。特定のランナーを対象にするには、runnerIds: ["[RUNNER-ID]"] も追加し、プレースホルダーをそのランナーの ID に置き換えてください。オブジェクトストレージの前提条件については、サンドボックスに AI Object Storage へのアクセスを許可するを参照してください。指定できるフィールドはこの一覧に限られます。このエンドポイントでは、ボリューム、インスタンスタイプ、ランタイムクラス、イメージをプルするための認証情報、公開サービスは利用できません。これらが必要な場合は、POST /v1/sandboxes を使用してください。

サンドボックスを作成する

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

contents を base64 エンコードして POST します。

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 @-

応答は STATE_CREATING 状態のサンドボックスです。STATE_RUNNING または終端状態になるまで、その sandboxId をポーリングします。

Poll the sandbox

export SANDBOX_ID="[SANDBOX-ID]"

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

返された spec には 2 つのコンテナーがあり、main はプライマリとして指定され、HELPER_HOST は引き続き helper に設定されています。サンドボックス内では、helper は 127.0.0.1 に解決されます。作成を安全に再試行するには、requestId を送信します。同じ requestId と同じ宣言済みの入力を使用すると、既存のサンドボックスが返されます。同じ requestId でもバイト列が異なる場合は、空白のみの変更も含め、理由 CWSANDBOX_REQUEST_ID_CONFLICT とともに ALREADY_EXISTS が返されます。

TypeScript からサンドボックスを作成する

TypeScript ソフトウェア開発キット (SDK) 1.0.0 では、runFromFile() と withSandboxFromFile() を通じて Compose をサポートしています。あらかじめ TypeScript クライアントのセットアップを完了し、sandbox-client.mts ファイルをこのスクリプトと同じディレクトリに保存してください。サンドボックスを作成するの compose.yaml ファイルを使用します。withSandboxFromFile() は、サンドボックスが準備完了になるまで待機してからコールバックを実行します。コールバックが値を返すか例外をスローすると、サンドボックスを停止します。

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,
  },
);

これらのファイルがあるディレクトリで、スクリプトを実行します：

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

スクリプトは Compose sandbox ready を出力し、サンドボックスを停止します。 string 引数は常にファイルパスとして扱われます。インラインの YAML を渡すには、new TextEncoder().encode(yaml) で UTF-8 のバイト列に変換して渡してください。SDK はバイト列を再整形せずにそのまま送信します。ファイルサイズは API の上限である 256 KiB 以内に収めてください。バージョン 1.0.0 では primaryService は必須で、ファイル内に定義されたサービス名を指定する必要があります。defaultResources は、project 全体ではなくサービスごとに CPU とメモリを割り当てます。GPU リソースには対応していません。本来ビルドが必要なサービスには、imageOverrides を使用してプル可能なイメージを指定してください。Compose のサポートに記載の制限は SDK にも適用されます。ライフサイクルを手動で管理する場合は、runFromFile() が返すサンドボックスのハンドルを使用し、finally ブロック内で停止してください。両メソッドのシグネチャについては、SandboxClient を参照してください。サポートされるオプションについては、SandboxRunFromFileOptions を参照してください。

Compose のサポート

すべてのサービスは、1 つの Pod と 1 つのネットワーク namespace を共有します。サービス名は 127.0.0.1 に解決されるため、HELPER_HOST: helper や API_BASE: http://main:8080 などの値は、ファイルを書き換えずに使用できます。サンドボックスには、サービスごとの IP アドレス、ブリッジネットワーク、レプリカはありません。以下の動作は Docker Compose と異なります。

起動は逐次実行されます。 プライマリ以外の各サービスは、プライマリより先に、順番に起動します。これを考慮して maxLifetimeSeconds を設定してください。サービスが準備完了にならない場合、サンドボックスは STATE_CREATING のままになります。
RUNNING はプライマリのみをトラッキングします。 起動後にヘルパーがクラッシュしても、サンドボックスは失敗しません。
healthcheck は exec のみの起動プローブになります。 test は string、CMD、CMD-SHELL、または NONE である必要があり、期間は整数秒で指定する必要があります。プローブの再試行回数を使い切ると、コンテナーは異常とマークされるのではなく、停止されます。
ポートは Pod 内にとどまります。 expose と ports は待ち受けポートを宣言しますが、外部には公開されません。
ビルド済みのイメージを使用してください。 すべてのサービスについて、ファイル内の image: または imageOverrides のエントリで、プル可能なイメージを指定してください。build: が必要なままのサービスは、UNIMPLEMENTED を返します。
command と entrypoint は Docker のシェル形式と exec 形式に従います。 イメージのデフォルトを使用するには、これらを省略してください。明示的な null と [] は拒否されます。
GPU はプライマリ専用です。deploy.resources.reservations.devices で gpu 機能と正の整数の個数を指定します。
名前は DNS-1123 ラベルである必要があります (My_App ではなく my-app) 。また、予約済みの接頭辞 cw-object-store-agent、cw-object-store-agent-restore、dns-egress は使用できません。

サポートされないキー

ドキュメントは自己完結している必要があります。ゲートウェイはディスクを読み取らず、環境変数も展開しません。認識されないキーは無視されず、問題のあるフィールドのパスとともに拒否されます。

拒否される項目	メモ
`$VAR` および `${VAR}` の補間	リテラルの `$` には `$$` を記述してください。
`include`, `extends`, `env_file`	インラインの `environment` または `env` のみ使用してください。値のないキーと `null` 値も拒否されます。
`volumes`, `tmpfs`, `configs`, `secrets`, バインドマウント	名前付きボリュームを使用する project はインポートできません。
`restart`, `logging`, `profiles`, `stdin_open`, `tty`, `scale`	このランタイムでは実装されていません。
`network_mode`, `pid`, `ipc`, `extra_hosts`, 名前付きネットワーク	Pod は 1 つ、namespace は 1 つです。
ホストからコンテナーへのポートマッピング、バインドアドレス、ポート範囲、TCP 以外のプロトコル、サービス間で重複するポート	エントリごとに TCP 待ち受けポートは 1 つで、サンドボックス内で一意である必要があります。
`depends_on: service_completed_successfully`、またはプライマリを対象とする `depends_on`	`service_healthy` と `service_started` はプライマリ以外のサービスを対象にできます。`service_healthy` を使用するには、対象サービスで有効なヘルスチェックが設定されている必要があります。
Compose のメモリ表記 (`512m`, `2g`, `512mb`)	`512Mi` や `1Gi` などの Kubernetes の数量表記を使用してください。
名前による `user` 値 (`nobody`)	数値の UID を使用してください。

ゲートウェイは version、project の name、labels、x-* 拡張キーを無視します。labels がサンドボックスに渡されることを前提にしないでください。

よくあるエラー

フィールド違反は、パスと制限値を示す BadRequest の詳細として返されます。ドキュメントの内容は引用されません。

状況	コードと理由	フィールド
`type` が省略されている	`INVALID_ARGUMENT`、`CWSANDBOX_INVALID_REQUEST`	`type`
Compose 以外のタイプ	`UNIMPLEMENTED`、`CWSANDBOX_NOT_IMPLEMENTED`	`type`
`primaryService` が省略されている、または不明	`INVALID_ARGUMENT`、`CWSANDBOX_INVALID_REQUEST`	`primary_service`
`image:` と `build:` のどちらも指定されていないサービス	`INVALID_ARGUMENT`、`CWSANDBOX_INVALID_REQUEST`	`contents.services.<name>`
`build:` が必要なままのサービス	`UNIMPLEMENTED`、`CWSANDBOX_NOT_IMPLEMENTED`	`contents.services.<name>.build`
ファイルが 256 KiB を超えている、または単一の UTF-8 YAML ドキュメントではない	`INVALID_ARGUMENT`、`CWSANDBOX_INVALID_REQUEST`	`contents`
サポートされていない Compose キー	`INVALID_ARGUMENT`、`CWSANDBOX_INVALID_REQUEST`	キーのパス
`requestId` が同じでバイト列が異なる	`ALREADY_EXISTS`、`CWSANDBOX_REQUEST_ID_CONFLICT`	なし

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

Compose ファイルからサンドボックスを作成する

始める前に

リクエストフィールド

サンドボックスを作成する

TypeScript からサンドボックスを作成する

Compose のサポート

サポートされないキー

よくあるエラー

関連情報

​始める前に

​リクエストフィールド

​サンドボックスを作成する

​TypeScript からサンドボックスを作成する

​Compose のサポート

​サポートされないキー

​よくあるエラー

​関連情報

始める前に

リクエストフィールド

サンドボックスを作成する

TypeScript からサンドボックスを作成する

Compose のサポート

サポートされないキー

よくあるエラー

関連情報