1.0 プレビュー

Sandbox SDK 1.0 は、SDK の次のメジャーリリースです。npm の @next タグでプレビューとして利用できます。現在の安定版パッケージは、既存アプリ向けに公開されたままです。

Sandbox は引き続き Cloudflare Containers 上で隔離された処理を実行します。1.0 プレビューは、その基盤の上にある より薄い SDK です。短時間の処理と長時間実行の両方に 1 つのプロセスハンドルを使い、セッションベースのコマンド状態はなく、トランスポートの選択もなく、ターミナルは第一級の PTY として扱い、コードインタープリターはオプトインの拡張です。

新規プロジェクトは @cloudflare/sandbox@next から始め、このセクションに沿って進めることをおすすめします。既存アプリは準備ができたら移行し、1.0 が安定版になったときにすぐ使えるようにします。移行 を参照してください。

メインの Sandbox ドキュメント は、現在の安定版パッケージを説明しています。プレビュー API と移行手順は この セクションを使います。

npm i @cloudflare/sandbox@next

yarn add @cloudflare/sandbox@next

pnpm add @cloudflare/sandbox@next

bun add @cloudflare/sandbox@next

Worker パッケージとサンドボックスのコンテナイメージは、同じプレビュー系統からデプロイします。プレビューの Worker パッケージと安定版のコンテナイメージを混ぜないでください（逆も同じです）。継続的なデプロイは Sandbox アプリケーションをデプロイする を参照してください。破壊的な切り替えは 移行 を参照してください。

安定版パッケージでは、コマンドの実行方法がいくつか増えました（exec、startProcess、execStream）。起動をまたいだ任意のセッション状態や、Durable Object とコンテナ間のトランスポート選択もあります。その面は動いていましたが、考え方が重複し、コンテナ上のサンドボックスの実際の動きが見えにくくなっていました。

プレビューでは、より小さい契約にまとめます。

手順: 移行。考え方: プロセス実行 と Sandbox のライフサイクル。

安定版: sandbox.exec(string) は、コマンドが 終了 したときにバッファ済み出力で解決します。長時間実行のサービスとストリーミングは別 API（startProcess、execStream）です。

プレビュー: sandbox.exec() は argv を受け取り、プロセスが 開始 したときに解決します。同じハンドルが短いコマンドと長時間実行のサービスの両方をカバーします。

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

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

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

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

パイプや && などのシェル機能には、明示的なシェルが必要です。例: ['/bin/bash', '-lc', 'cd app && npm test']。プロセスが必要とする場合は、各 exec() に cwd と env を渡します。詳細: プロセス実行、Processes API。

安定版: デフォルトセッションは、exec() 呼び出しをまたいで作業ディレクトリと環境変数を保持できます。アプリは createSession() で名前付きセッションも作成できます。

プレビュー: SDK 上にセッション実行はありません。各 exec() は独立しています。起動ごとに cwd と env を渡すか、複数ステップのシェル構文を 1 つの明示的なシェル argv にまとめます。エンドユーザーの隔離は、1 つのサンドボックス内のセッションではなく、別々のサンドボックスで行います。環境モデル: 環境変数。

安定版: ブラウザーシェルは、多くの場合 sandbox.terminal(request) とセッションヘルパー、xterm の sessionId を使います。

プレビュー: ターミナルは PTY リソースです。createTerminal、getTerminal、listTerminals、terminal.connect(request) を使います。xterm ヘルパーは terminalId を使います。ターミナル を参照してください。

安定版: インタープリターメソッドは Sandbox 上にあります。

プレビュー: サブクラスにインタープリターを取り付けてから、sandbox.interpreter.* を呼び出します。コードインタープリター を参照してください。

安定版: アプリは Durable Object とコンテナ間で HTTP、WebSocket、RPC を選べます。

プレビュー: SDK は常に RPC を使います。SANDBOX_TRANSPORT、getSandbox() の transport オプション、setTransport() を削除します。代替設定は不要です。

これは 新しいコンテナ製品ではありません。サンドボックスは、安定した sandbox ID で指定します。

const sandbox = getSandbox(env.Sandbox, "user-123");

const sandbox = getSandbox(env.Sandbox, "user-123");

そのサンドボックスは コンテナ 内で動きます。ID は安定しています。背後のコンテナインスタンスは、常に同じものとは限りません。開始したプロセスとターミナルは、現在の コンテナにだけ存在します。コンテナが停止または置き換わると、それらのプロセスとターミナルは消えます。古いハンドルは、同じ sandbox ID の新しいコンテナに静かに接続し直すのではなく、失敗して閉じます。

コンテナの停止と置き換えは、安定版でもすでに起きていました。プレビューでは、プロセスとターミナルの API がその寿命を正直に表します。全体のモデル: Sandbox のライフサイクル。プロセスの詳細: プロセスの存続期間。復旧: エラーと復旧。

これらは引き続き利用できます。シグネチャはメインの Sandbox ドキュメントを使い、セッションやトランスポートのオプションがまだ書かれているページでは、それらを無視してください。

• ファイル と ファイル監視
• ストレージ と バックアップ
• ポート と トンネル
• ライフサイクルオプション と サンドボックスオプション（削除されたセッション / トランスポートフィールドを除く）
• アウトバウンドトラフィック（認証情報の注入とエグレスポリシー）

@next のプロセス環境については、このセクションの 環境変数 を使います。

エージェント向けに Cloudflare Skills ↗ をインストールします（Agent setup）。@next での作業には sandbox-next を使います（新規プロジェクトにおすすめです）。現在の安定版パッケージの既存アプリは、移行の準備ができるまで sandbox-stable を使い、その後 sandbox-migrate-to-next を使います。安定版のまま非推奨 API を片付ける手順は、2026 年の非推奨ガイド と sandbox-stable にあります。

現在の安定版パッケージを使い続ける間は、メインのドキュメントを使います。

• 始める
• コマンド
• セッション
• 2026 年の非推奨移行