Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

1.0 プレビュー

最終更新 Markdown で表示Agent セットアップ

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

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

1.0 が目指すもの

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

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

やりたいこと プレビューでの方法
プログラムを実行する exec(argv) → 起動に成功したらプロセスハンドル
出力を見る、または準備完了を待つ ハンドル上の output()、logs()、waitForExit()、waitForLog()、waitForPort()
プロセスを止める kill(signal?)(数値シグナル。デフォルトは 15)
対話的な複数ステップでシェル状態を保つ 隠れたデフォルトセッションではなく、ターミナル(PTY)
Python / JS のセルを実行する Sandbox サブクラス上の コードインタープリター 拡張
コンテナのコントロールプレーンと通信する 常に RPC。トランスポート設定なし

手順: 移行。考え方: プロセス実行 と 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 のプロセス環境については、このセクションの 環境変数 を使います。

ここから始める

始める

@next をインストールし、最初のプロセスハンドルを動かします。

プロセス実行

exec() の動き、プロセスハンドル、プロセスの存続期間です。

エラーと復旧

よくある失敗のあとで、再試行、確認、再起動する方法です。

環境変数

setEnvVars、起動ごとの env、プロセスが環境を受け取る方法です。

API リファレンス

@next 向けのプロセス、ターミナル、エラー、インタープリターのシグネチャです。

拡張

コードインタープリターとその他の任意機能を取り付けます。

コーディングエージェント

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

安定版ドキュメント

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

役に立ちましたか?