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

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

> サンドボックスの作成やコマンドの実行方法を説明し、TypeScript ソフトウェア開発キット (SDK) の API を紹介します。

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

## 前提条件

Node.js 22 以降と、ECMAScript モジュール (ESM) のプロジェクトを使用してください。`tsx` で実行するには、例のコードを `.mts` ファイルとして保存してください。

[認証情報の選択と取得](https://docs.coreweave.com/ja/products/sandboxes/placement.md#choose-and-get-credentials) から認証情報を選択します。例ではサーバーレスキャパシティを使用します。CoreWeave Kubernetes Service (CKS) に配置する場合は、[ランナーを有効化](https://docs.coreweave.com/ja/products/sandboxes/get-started-cks.md)したうえで、`runnerIds` 配列が空でない CoreWeave API アクセストークンを使用してください。

SDK をインストールします:

```bash theme={"system"}
npm install @coreweave/cwsandbox@1.0.0
```

## クライアントを作成する

使用する認証情報に応じてエントリポイントを選択します。どちらのファクトリーも [`SandboxClient`](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/client#sandboxclient) を返します。ルートの `@coreweave/cwsandbox` エントリポイントは、タイプ、定数、エラーをエクスポートします。クライアントは `/wandb` または `/node` から作成します。

該当するタブのコードを、他のサンプルファイルと同じディレクトリに `sandbox-client.mts` として保存します。このコードは認証方式を選択し、クライアントをエクスポートします。認証情報はコードには含まれず、環境変数に保持されます。

> [tab] Forge API キー
>
> `[WANDB-API-KEY]` を Forge API キーに置き換えます。
>
> ```bash theme={"system"}
> export WANDB_API_KEY="[WANDB-API-KEY]"
> ```
>
> ```typescript title="sandbox-client.mts" theme={"system"}
> import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";
>
> export const client = createSandboxClientFromEnv();
> ```
>
> Forge のチームを指定するには、`WANDB_ENTITY` を設定します。オプションを明示的に指定する方法については、[Forge クライアントファクトリー](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/wandb.md)を参照してください。

> [tab] CoreWeave API アクセストークン
>
> `[API-ACCESS-TOKEN]` をトークンに置き換えます。
>
> ```bash theme={"system"}
> export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
> ```
>
> ```typescript title="sandbox-client.mts" theme={"system"}
> import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";
>
> export const client = createSandboxClientFromEnv();
> ```
>
> このファクトリーは `CWSANDBOX_BASE_URL` も読み取ります (デフォルトは `https://api.cwsandbox.com`) 。オプションを明示的に指定する方法については、[Node クライアントファクトリー](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/node.md)を参照してください。

## コマンドを実行する

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

```typescript title="hello.mts" theme={"system"}
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);
```

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

```bash theme={"system"}
npx --yes --package=tsx tsx hello.mts
```

このスクリプトは `Hello!` を出力し、サンドボックスを停止します。

`tsx` で実行する場合や TypeScript でコンパイルする場合、`./sandbox-client.mjs` のインポートはローカルの `sandbox-client.mts` ファイルに解決されます。

`commands.run()` は標準出力 (stdout) と標準エラー出力 (stderr) をバッファリングし、`exitCode` を含む [`ProcessResult`](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/commands#processresult) を返します。出力をストリーミングするには、`commands.start()` を使用します。

複数の操作でサンドボックスを使い続けるには、`client.create()` を使用し、`finally` ブロックでサンドボックスを停止します。詳細は [サンドボックスのライフサイクルリファレンス](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/sandboxes.md#sandbox) を参照してください。

## エラーを処理する

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

```typescript theme={"system"}
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` が送出されます。エラーの階層と利用可能なメタデータについては、[エラー](https://docs.coreweave.com/ja/products/sandboxes/typescript-client/ref/errors.md)を参照してください。

## API リファレンス

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

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

Compose を使用した例については、[TypeScript からサンドボックスを作成する](https://docs.coreweave.com/ja/products/sandboxes/create-from-file.md#create-a-sandbox-from-typescript)を参照してください。