サンドボックスの配置とスピルオーバー

配置によって、サンドボックスを実行するコンピュートが決まります。サーバーレスでは、CoreWeave が管理するマネージドコンピュートを使用します。クラスター配置では、組織内の CoreWeave Kubernetes Service (CKS) クラスターのコンピュートを使用します。スピルオーバーを使用すると、最初の配置が失敗した場合に、もう一方のモードでサンドボックスの作成が再試行されます。

配置モードを比較する

キャパシティとポリシーを誰が管理するかに基づいて、モードを選択します。

	サーバーレス	CKS
サンドボックスの実行場所	CoreWeave が管理するコンピュート	お使いの CKS クラスター内のコンピュート
ポリシーの設定者	CoreWeave	お客様の管理者
セットアップ	Forge または CoreWeave の認証情報で認証します	クラスターでランナーを有効にします
配置の制御	プラットフォームが管理します。クラスターを選択する必要はありません。	Python では、条件を満たす任意のクラスターを使用できます。配置先を制限するには、ランナー ID を指定します。TypeScript ではランナー ID の指定が必須です。
リソース	サンドボックスごとに CPU とメモリを選択します	クラスターのポリシーの範囲内で CPU とメモリを選択します
認証情報	Forge APIキーまたは CoreWeave API アクセストークン	CoreWeave API アクセストークン
適した用途	クラスターのキャパシティを管理せずにサンドボックスを実行したい場合	自社クラスターのキャパシティを使用し、リソースとネットワークのポリシーを制御したい場合

最初のサンドボックスを作成するには、サーバーレスのクイックスタートまたは独自のコンピュートを使用するの手順に従ってください。

認証情報を選択して取得する

使用する認証情報によって、サンドボックスを所有し、その使用量が請求されるアカウントが決まります。Forge APIキーはサーバーレスサンドボックスに対応しています。CoreWeave API アクセストークンは、サーバーレスサンドボックスとクラスターサンドボックスの両方に対応しています。認証情報は、配置モードに関係なく、環境変数と認証方式によって特定されます。

認証情報	環境変数	Python の認証方式	配置
Forge APIキー (W&B 認証)	`WANDB_API_KEY`	`AuthStrategy.WANDB`	サーバーレス
CoreWeave API アクセストークン	`CWSANDBOX_API_KEY`	`AuthStrategy.COREWEAVE_API_KEY`	サーバーレスまたは CKS

両方の変数が設定されている場合でも、使用する認証情報を 1 つ明示的に選択してください。サンドボックスの作成、再接続、一覧表示、停止には、同じアカウントを使用してください。

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

CoreWeave コンソールのアカウントを持っていない場合、または Forge の請求を利用したい場合は、Forge APIキーを選択します。

Forge APIキーの設定を開きます。サインインするか、同じリンクからアカウントを作成します。
APIキーをコピーし、クライアントを実行するターミナルで環境変数として設定します。
export WANDB_API_KEY="[WANDB-API-KEY]"

Python では cwsandbox[wandb] をインストールし、auth=AuthStrategy.WANDB を選択します。TypeScript では @coreweave/cwsandbox/wandb エントリポイントを使用します。WANDB_API_KEY を設定しただけでは、Python クライアントはデフォルトの CoreWeave 認証から切り替わりません。完全な設定例については、サーバーレスのクイックスタートを参照してください。

CoreWeave 組織の請求を利用する場合、またはその組織のクラスターでサンドボックスを実行する場合は、CoreWeave を選択します。

サンドボックスを実行するには、Sandbox User ロールを付与するアクセスポリシーを作成または更新するよう管理者に依頼します。ランナーを有効化してそのポリシーを設定する管理者には、Sandbox Admin ロールが必要です。このロールにはサンドボックスの実行権限も含まれます。アクセスポリシーを作成するおよびサンドボックスのロールを参照してください。
Tokens ページで Create Token をクリックし、トークンの詳細を入力して Create をクリックします。
Token Secret をコピーし、クライアントを実行するターミナルで環境変数として設定します。
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

トークンを作成できない場合は、Access Token User ロールの付与を管理者に依頼してください。トークンシークレットは一度しか表示されません。詳細については、次を参照してください: API アクセストークンを管理する。Python では AuthStrategy.COREWEAVE_API_KEY を選択します。TypeScript では @coreweave/cwsandbox/node からクライアントをインポートします。

配置モードを選択する

Python と TypeScript のどちらも、サーバーレス配置とクラスター配置をサポートしています。デフォルトはサーバーレスです。サポートされるモードの値については、PlacementMode リファレンスを参照してください。クラスターの例はどちらも CWSANDBOX_API_KEY を読み取ります。まず認証情報のセットアップを完了してください。次に、独自のコンピュートを使用するの手順に従ってランナーを有効にするか、サーバーレスのクイックスタートの手順に従って TypeScript クライアントをインストールします。クラスター配置を明示的に選択するには、次のようにします。

Python
TypeScript

placement_mode="cks" を使用します。配置先を特定のランナーに限定するには、runner_ids を追加します。

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)

runner_ids を指定しない場合、CKS 配置では組織内の条件を満たす任意のランナーが使用される可能性があります。サーバーレスの場合は、両方のフィールドを省略するか、runner_ids を指定せずに placement_mode="serverless" を設定します。

CKS 配置を選択するには、CoreWeave のエントリポイントと空でない runnerIds 配列を使用します。

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

const client = createSandboxClientFromEnv();
const result = await client.withSandbox(
  async (sandbox) => sandbox.commands.run(["echo", "Hello!"]),
  {
    runnerIds: ["[RUNNER-ID]"],
    resources: { cpu: "1", memory: "1Gi" },
  },
);
console.log(result.stdout);

サーバーレス配置を使用する場合は、runnerIds を省略します。

モード間のスピルオーバー

自動スピルオーバーは Python クライアントで利用できます。TypeScript クライアントはどちらの配置モードも選択できますが、自動スピルオーバーには対応していません。スピルオーバーは、キャパシティ不足や適切なランナーがないなど、対象となる配置エラーが発生した場合に、もう一方のモードでサンドボックスの作成を 1 回だけ再試行します。実行中のサンドボックスをモード間で移動することはありません。サーバーレスへのアクセス権と設定済みの CKS ランナーの両方を備えた組織の CoreWeave API アクセストークンを使用してください。Forge の APIキーだけでは CKS にアクセスできません。 CKS を優先し、利用できない場合にサーバーレスへフォールバックするには、placement_spillover="cks_then_serverless" を設定します。

from cwsandbox import AuthStrategy, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_spillover="cks_then_serverless",
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    print(sandbox.exec(["echo", "Hello!"]).result().stdout)

この例では、両方の試行で CPU とメモリを指定しています。モードごとに独自のポリシーが適用されるため、リクエストは実行先のモードのポリシーを満たす必要があります。フォールバックを制御するには、placement_spillover に次のいずれかのオプションを設定します。

オプション	最初の試行	フォールバック	制約
`strict` (デフォルト)	選択した配置モード	なし	テンプレートから作成する場合、または `run_from_file()` を使用する場合は必須
`cks_then_serverless`	CKS	サーバーレス	`placement_mode` は `"cks"` にするか、省略する必要があります
`serverless_then_cks`	サーバーレス	CKS	`placement_mode` は `"serverless"` にするか、省略する必要があります。`runner_ids` とは併用できません。

サポートされるフォールバック値については、PlacementSpillover リファレンスを参照してください。リソースとタイムアウトの設定については、サンドボックスの設定を参照してください。