サンドボックス TypeScript クライアント

@coreweave/cwsandbox TypeScript クライアントを使用すると、CoreWeave のサンドボックスを作成および管理できます。このガイドでは、クライアントの作成、サンドボックスでのコマンドの実行、SDK エラーの処理方法について説明します。サンドボックスの TypeScript の例と API リファレンスでは、バージョン 1.0.0 を使用しています。各ガイドに沿って作業する際は、このバージョンをインストールしてください。

前提条件

Node.js 22 以降と、ECMAScript モジュール (ESM) のプロジェクトを使用してください。tsx で実行するには、例のコードを .mts ファイルとして保存してください。認証情報の選択と取得から認証情報を選択します。例ではサーバーレスキャパシティを使用します。CoreWeave Kubernetes Service (CKS) に配置する場合は、ランナーを有効化したうえで、runnerIds 配列が空でない CoreWeave API アクセストークンを使用してください。 SDK をインストールします:

npm install @coreweave/cwsandbox@1.0.0

クライアントを作成する

使用する認証情報に応じてエントリポイントを選択します。どちらのファクトリーも SandboxClient を返します。ルートの @coreweave/cwsandbox エントリポイントは、タイプ、定数、エラーをエクスポートします。クライアントは /wandb または /node から作成します。該当するタブのコードを、他のサンプルファイルと同じディレクトリに sandbox-client.mts として保存します。このコードは認証方式を選択し、クライアントをエクスポートします。認証情報はコードには含まれず、環境変数に保持されます。

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

[WANDB-API-KEY] を Forge API キーに置き換えます。

export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

Forge のチームを指定するには、WANDB_ENTITY を設定します。オプションを明示的に指定する方法については、Forge クライアントファクトリーを参照してください。

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

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

このファクトリーは CWSANDBOX_BASE_URL も読み取ります (デフォルトは https://api.cwsandbox.com) 。オプションを明示的に指定する方法については、Node クライアントファクトリーを参照してください。

コマンドを実行する

コールバックの終了に合わせて停止させたい処理には、withSandbox() を使用します。withSandbox() は、サンドボックスが準備完了になるまで待機してからコールバックを呼び出し、コールバックが値を返すか例外をスローした時点でサンドボックスを停止します。

hello.mts

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

const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    containerImage: "python:3.11",
    resources: { cpu: "1", memory: "1Gi" },
  },
);

console.log(result.stdout);

スクリプトを実行します。

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

このスクリプトは Hello! を出力し、サンドボックスを停止します。 tsx で実行する場合や TypeScript でコンパイルする場合、./sandbox-client.mjs のインポートはローカルの sandbox-client.mts ファイルに解決されます。 commands.run() は標準出力 (stdout) と標準エラー出力 (stderr) をバッファリングし、exitCode を含む ProcessResult を返します。出力をストリーミングするには、commands.start() を使用します。複数の操作でサンドボックスを使い続けるには、client.create() を使用し、finally ブロックでサンドボックスを停止します。詳細はサンドボックスのライフサイクルリファレンスを参照してください。

エラーを処理する

isCWSandboxError() を使用して型が不明なエラーを絞り込み、その code を確認します。

import { isCWSandboxError } from "@coreweave/cwsandbox";
import { client } from "./sandbox-client.mjs";

try {
  await client.withSandbox(async (sandbox) => {
    await sandbox.commands.run(["false"], { check: true });
  });
} catch (error) {
  if (isCWSandboxError(error)) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

check: true を指定した場合、コマンドが 0 以外の終了コードで終了すると CWSandboxExecutionError が送出されます。エラーの階層と利用可能なメタデータについては、エラーを参照してください。

API リファレンス

このリファレンスには、メソッドのオーバーロード、パラメーターと戻り値のタイプ、オプションフィールド、継承されたタイプなど、公開されている宣言がそのまま記載されています。SDK のコメントには、レビュー済みの修正が反映されています。

リファレンス	内容
クライアントとディスカバリー	作成、再接続、一覧表示、クリーンアップ、およびテンプレートや Compose ファイルからの起動。
サンドボックスとライフサイクル	サンドボックスハンドル、起動オプション、スナップショット、ライフサイクルの状態。
コマンドとターミナル	コマンドの実行、Process ハンドル、標準入力 (stdin)、対話型ターミナル。
ファイル	バッファリングおよびストリーミングによるファイル操作と、マウントされたファイル。
ログ	サンドボックスログの読み取りとストリーミング。
ネットワークとサービス	ネットワークルール、サービス、エンドポイント。
リソースとシークレット	リソースリクエストと制限、およびシークレットの入力。
リクエストオプションとデフォルト	タイムアウト、キャンセル、データプレーンのモード、デフォルトの定数。
エラー	エラークラス、エラーコード、バックエンドの理由定数。
Node クライアントファクトリー	CoreWeave トークンによる認証とクライアントの構築。
Forge クライアントファクトリー	Forge の認証とチームの選択。

Compose を使用した例については、TypeScript からサンドボックスを作成するを参照してください。