sandbox-migrate-to-next

stable → Sandbox SDK 1.0 プレビュー（@next）への移行

移行を実施してください。手順に従って順番に進めます。詳しい情報はドキュメントに記載されています。各手順で詳細が必要な場合は、リンク先のページを取得してください。

開発者向けガイド：移行 · 1.0 プレビュー

新規プロジェクトは、このスキルではなく、@next（sandbox-next）から開始してください。日常的な stable での作業 → sandbox-stable。@next に移行せずに非推奨 API を整理する場合は、必要に応じてまず2026 年の非推奨ガイドを確認してください。

既存のアプリは、1.0 が安定版リリースになったときに備え、可能になり次第移行してください。ユーザーの同意なしに、本番環境への切り替えを強行しないでください。

記憶に頼らず、インストール済みの @next の型と移行ドキュメントを優先してください。

ワークフロー

1. 確認：必須ルールと置き換え一覧
2. 監査：コードベースを調べ、該当箇所と目標の形を一覧にする
3. 確認：ユーザーに確認する（切り替え、ブリッジ、Python イメージ、不明な箇所）
4. アップグレード：パッケージ、イメージ、コード
5. 検証

ユーザーの判断が必要な手順の後は停止してください。

必須ルール

• Worker パッケージとコンテナイメージは、同じ @next 系列でなければなりません。
• 本番環境への切り替えでは、コンテナを即時にロールアウトします。stable と @next の制御プロトコルには相互互換性がありません。段階的なロールアウトでは、混在によって動作しない時間が発生します。処理中のコンテナ作業が停止する可能性があります。
• 切り替え後、await sandbox.exec(...) はプロセスの起動を意味し、コマンドの完了を意味しません。
• Argv はそのまま実行されます（暗黙にシェルは起動しません）。シェル構文を使うには、シェルのバイナリを明示する必要があります。
• プロセスハンドルには stdin がありません → インタラクティブな入力にはターミナルを使用してください。
• 監視の timeout／AbortSignal がキャンセルするのは待機のみであり、プロセスではありません。
• すべてのエラーに対して、単一の再試行ループを使わないでください。
• API を捏造しないでください（core の gitCheckout、プロセスの stdin、文字列実行の完了ヘルパーなど）。
• セルフデプロイのブリッジは stable のままです（まだプレビュー系列には含まれません）。

置き換え一覧

stable	@next
SANDBOX_TRANSPORT / transport / setTransport	削除 — RPC のみ
await sandbox.exec("cmd") → バッファリングされた結果	await sandbox.exec(argv) → ハンドル、その後 output／待機
execStream / startProcess	同じハンドルを使用：logs、waitFor*、kill
デフォルト／名前付きセッション	なくなりました — 起動ごとに cwd／env を指定するか、シェルスクリプトを 1 つ実行
sandbox.terminal(request) / セッションのターミナル	createTerminal + terminal.connect(request)
xterm の sessionId	terminalId
Sandbox 上のインタープリターメソッド	withInterpreter → sandbox.interpreter.*
gitCheckout	exec 経由で argv の git を実行
文字列の kill シグナル	数値のみ
ファイル、マウント、バックアップ、ポート、トンネル、proxyToSandbox	ほぼ変更なし（stable のページにあるセッション／トランスポート関連の内容は無視してください）

詳細：移行 · 移行後の日常的な作業 → sandbox-next

監査

rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'

あわせて確認：文字列を使った exec(、cd の後に別の exec を呼び出す箇所、Sandbox 上の裸の createCodeContext／runCode。

確認（必要に応じて質問）

• --containers-rollout=immediate を使った本番環境への切り替えは問題ありませんか（実行中のプロセス／ターミナル／ストリームが停止する可能性があります）？
• セルフデプロイのブリッジですか？その場合は stable のままにしてください。
• Python インタープリターを使用しますか？ → -python イメージバリアント
• 置き換え一覧で扱われていない呼び出し箇所はありますか？

アップグレード

パッケージとイメージ

npm install @cloudflare/sandbox@next

FROM cloudflare/sandbox:next
# Python: cloudflare/sandbox:next-python

next に固定せずに使用する場合は、Worker とイメージで同じプレリリースタグを使用してください。

領域別のコード

マップに従って置き換えます。各領域について、慣例に頼らず、ドキュメントに基づいて実装してください。

領域	ドキュメント
コマンド／ハンドル／待機	プロセス · Processes API
cwd／env／シークレット	環境 · アウトバウンドトラフィック
セッションの削除	移行 · ライフサイクル
ターミナル	ターミナル
インタープリター	インタープリター
エラー	エラー
リクエストをまたぐ永続的なジョブ	プロセスの実行 — 有効期間／永続性

コマンド（形式）：

// Before (stable)
const result = await sandbox.exec("npm test");

// After (@next)
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
  cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // numeric; default 15

ターミナル（形式）：

const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("terminal gone", { status: 410 });
return t.connect(request, { cursor, cols, rows });

インタープリター（形式）：

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
  interpreter = withInterpreter(this);
}

Git（形式）：

const clone = await sandbox.exec(
  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
  { cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

トランスポート設定はすべて削除してください。セッション API を削除してください。ユーザーごとに別々のサンドボックス IDで分離してください。

デプロイの切り替え

まずステージング／ブランチで行います。本番環境では、対応する Worker とイメージを一度にデプロイします。

npx wrangler deploy --containers-rollout=immediate

rollout_active_grace_period はデフォルトの 0 のままにするか、値が引き上げられている場合は 0 に設定します。切り替え後は、デプロイ前のプロセス ID／ターミナル ID は無効になります。詳細：移行 · コンテナのロールアウト

検証

1. ロックファイルと Dockerfile が同じ @next 系列であること
2. @next に対して型チェックを行うこと
3. argv exec と output({ encoding: "utf8" }) のスモークテスト
4. 使用している場合は、長時間実行プロセス／ターミナル／インタープリターのスモークテスト
5. エラーを区別すること：利用不可／中断された RPC／古い状態／ローカル待機
6. サンドボックス環境に実際のシークレットがないこと
7. 削除した API を再度 grep で検索すること
8. 本番環境で --containers-rollout=immediate を使用したこと

これ以降、日々の作業では sandbox-next を使用します。

危険信号 — 停止して修正する

• @next の Worker と安定版のイメージ（またはその逆）を組み合わせている
• この切り替えに段階的なコンテナロールアウトを使用している
• await exec がコマンドの完了を意味すると見なしている
• cd／エクスポートが exec 呼び出し間で保持されると想定している
• あらゆるエラーに対して単一の再試行ラッパーを使っている
• gitCheckout、プロセス stdin、またはドキュメントに記載されていない API を作り出している
• デプロイ後も切り替え前のプロセス ID／ターミナル ID を保持している
• ユーザーの合意なしに本番環境への切り替えを強行している
• setEnvVars／起動時の env に実際のシークレットを設定している