移行する

1. ブランチまたはステージング環境で作業します。このガイドのコード移行を終えてから、本番は 1 回のデプロイで切り替えます。
2. 切り替えには短い停止時間が発生します。新しいイメージが古いイメージを置き換えると、実行中のプロセス、ターミナル、その他のコンテナ作業は止まります。
3. Worker 内の呼び出し箇所を洗い出します。
   • コマンド: exec、execStream、startProcess、文字列の kill シグナル、プロセスの stdin
   • セッションとトランスポート: createSession、enableDefaultSession、SANDBOX_TRANSPORT、setTransport
   • ターミナル: sandbox.terminal、セッションの terminal()、xterm の sessionId
   • インタープリター: 素の Sandbox 上の createCodeContext / runCode
   • Git: gitCheckout

安定版のクリーンアップ（RPC トランスポート、exposePort、ストリームヘルパー）が先に必要な場合は、2026 deprecation migration を完了してから、このガイドに戻ってください。

ファイル、マウント、バックアップ、ポート、トンネル、proxyToSandbox、およびほとんどのライフサイクルオプションはそのまま使えます。シグネチャは本編の Sandbox ドキュメントを参照してください。安定版のページがセッション、トランスポート選択、文字列の exec ヘルパー、または sandbox.terminal を説明している場合は、このプレビューの説明を優先してください。

npm i @cloudflare/sandbox@next

yarn add @cloudflare/sandbox@next

pnpm add @cloudflare/sandbox@next

bun add @cloudflare/sandbox@next

lockfile が @cloudflare/sandbox をプレビュービルドに解決していることを確認します。Dockerfile は、対応するプレビューイメージ（例: cloudflare/sandbox:next、または利用中の -python などのバリアント）を指すようにします。

プレビューの Worker パッケージと安定版のコンテナイメージを混ぜないでください。逆も同じです。両方とも同じ @next 系列である必要があります。

SANDBOX_TRANSPORT、getSandbox() の transport オプション、SandboxTransport 型、sandbox.setTransport() を削除します。代わりの設定は不要です。

安定版:

const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);

プレビュー:

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

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

ルール:

• await sandbox.exec(...) は 起動に成功した ことを意味し、コマンドが終わった ことではありません。
• 単一バイナリを実行する場合は、シェルなしの argv を優先します。cwd を指定して ['npm', 'test'] とします。
• output() のデフォルトは バイト ストリーム（Uint8Array）です。文字列が必要なときは { encoding: "utf8" } を渡します。
• 現在のプレビュー先端には、sandbox.run() 互換ヘルパーはありません。

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
	cwd: "/workspace/app",
});

// Default readiness mode is TCP. Use mode: "http" when you need an HTTP check.
await server.waitForPort(3000, { timeout: 60_000 });
// await server.waitForPort(3000, { mode: "http", path: "/health", timeout: 60_000 });

const stream = await server.logs({ follow: true, replay: true });
// consume stream...

await server.kill(); // numeric signal; default 15

プロセスハンドルの詳細（待機、ログイベント、kill、stdin なし）は Processes API を参照してください。

Worker リクエストをまたぐ場合は、server.id を保持し、そのプロセスが現在のコンテナでまだ動いているあいだだけ getProcess(id) で再開します。コンテナが止まっていると、getProcess は null を返すことがあります。以前のコンテナのハンドルを持っている場合は、古いハンドルのエラーになります。どちらの場合も、まだ実行する必要がある作業から新しい exec を開始します。プロセスの生存期間 を参照してください。

詳細は Environment variables を参照してください。

setEnvVars や起動時の env に、本番の API キーや長期のプロバイダークレデンシャルを入れないでください。シークレットは Worker に置き、プロセスが外部 API を呼ぶ必要があるときは outbound traffic ハンドラーで注入します。

createSession、getSession、deleteSession、およびコア呼び出しの sessionId オプションを削除します。

ユーザー分離は、1 つのサンドボックス内のセッションではなく、ユーザーごと（または信頼境界ごと）に 1 つのサンドボックス のままです。

Code interpreter を参照してください。最小構成は次のとおりです。

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

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

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

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

Python を実行する場合は -python イメージバリアントを使います。Worker パッケージとコンテナイメージは同じ @next 系列に揃えます。

sandbox.gitCheckout は削除されました。argv の exec で clone または fetch します。例:

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

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

安定版の sandbox.terminal(request)（およびセッションスコープの terminal()）を、プレビューのターミナルリソース API に置き換えます。

1. const terminal = await sandbox.createTerminal({ command: ['bash'], ... })
2. terminal.id をサンドボックス ID と一緒に保存します。
3. WebSocket アップグレード時: getTerminal(id) のあと terminal.connect(request, { cursor?, cols?, rows? })。
4. ブラウザでは、@cloudflare/sandbox/xterm は terminalId を使います。

詳細は Terminals、Terminals API を参照してください。

このガイドは @next 上の Worker SDK アプリケーション向けです。

自己デプロイの Sandbox bridge は安定版のままです。Worker パッケージ、コンテナイメージ、HTTP クライアントは、対応する安定版に揃えてください。bridge のデプロイと @cloudflare/sandbox@next を組み合わせないでください。

@next では サンドボックス ID は安定しますが、背後の コンテナ は置き換わることがあります。プロセスとターミナルは、現在のコンテナにだけ存在します。置き換え後、古いハンドルは失敗するので、作業をやり直します。

アイドル、再起動、今回の移行切り替えのあとに起きる、通常の動きです。全体のモデルは Sandbox lifecycle と プロセスの生存期間 です。復旧パターンは Errors and recovery です。カタログは Errors API です。

長時間実行の作業を移行するとき:

1. 保存した process.id や terminal.id だけでは、任意の遅延後やデプロイ後に再開できないと考えます。
2. 再起動に必要なコマンド、cwd、env、およびアプリのチェックポイントを永続化します。
3. 後続のリクエストでは、そのリソースが現在のコンテナでまだ動いている可能性があるときだけ getProcess(id) / getTerminal(id) を呼びます。null または古いハンドルのエラーになったら、保存した作業からやり直します。

少なくとも次のエラーは次のように扱います。

getProcess / getTerminal / list* はコンテナを起動しません。実行中のものがないときは例外ではなく null または [] を返します。

このガイドのコード移行は、先にブランチで終えます。本番の切り替えは、プレビューの Worker パッケージと対応するコンテナイメージを 1 回デプロイすることです。

安定版 Sandbox と @next は、制御プロトコルが異なります。混在ペアはどちらの方向でも動きません。新しい Worker コードと古いコンテナイメージ、古い Worker コードと新しいコンテナイメージは、どちらも失敗します。

通常の wrangler deploy では、Worker コードはすぐに有効になりますが、コンテナインスタンスは段階的に更新されることがあります。そのあいだ、新しい Worker コードが古いコンテナに届く窓が残ります。この移行では、コンテナを 1 ステップでロールアウトします。

npx wrangler deploy --containers-rollout=immediate

--containers-rollout=immediate は rollout_active_grace_period を上書きしません。切り替え時はこの設定をデフォルトの 0 のままにします（以前上げていた場合は 0 に戻します）。0 以外の猶予期間だと、新しい Worker がすでに稼働しているあいだ、稼働中の古いコンテナが長く対象に残り続けます。

本番の前に:

1. 切り替えをまたいで残したい作業を終えるか、止めます。
2. 前の節の、即時コンテナロールアウトのコマンドでデプロイします。
3. 新しいコンテナイメージがトラフィックを処理するまで待ちます。
4. デプロイ前のプロセス ID とターミナル ID は無効として扱います。その作業をやり直し、新しい ID を保持します。
5. 確認する のチェックを実行します。

移行後の通常デプロイは Deploy a Sandbox application を参照してください。ロールアウトオプションは Rollouts を参照してください。

1. lockfile と Dockerfile が同じ @next 系列にあることを確認し、--containers-rollout=immediate でデプロイします。
2. argv の exec を 1 回実行し、output({ encoding: "utf8" }) します。
3. waitForPort または logs を使い、長時間実行のプロセスを 1 つ動かします。
4. アプリがブラウザターミナルを使う場合: コンテナにまだあるあいだに作成、接続、getTerminal での再開を確認します。
5. アプリがその拡張を使うときだけインタープリターを試します（Python には -python が必要です）。
6. エラー処理が、利用不可、中断 / RPC、古いハンドル、ローカル待機タイムアウトを区別することを確認します。Errors and recovery を参照してください。
7. シークレットがサンドボックスの env に保存されていないことを確認します。必要なときはアウトバウンドハンドラーを使います。
8. 削除済み API（トランスポート、セッション、execStream、startProcess、sandbox.terminal、gitCheckout、xterm の sessionId）を再度 grep します。

エージェント向けに Cloudflare Skills ↗ をインストールします（Agent setup）。sandbox-migrate-to-next スキルが、この移行を実行します。@next 上の新規アプリには sandbox-next を使います。現行の安定版パッケージでの日常作業には sandbox-stable を使います。安定版のまま非推奨 API を片付ける手順は、このガイドの前（または代わり）に 2026 deprecation guide（および sandbox-stable）にあります。

• 1.0 preview の概要
• Get started
• Environment variables
• Sandbox lifecycle
• Process execution（プロセスの生存期間 を含む）
• Processes API
• Errors and recovery
• Errors API
• API reference
• Terminals
• Terminals API
• Code interpreter
• Extensions
• Troubleshooting
• Deploy a Sandbox application
• Deploy Containers
• Rollouts