Sandbox SDK — @next（1.0 プレビュー）
Cloudflare Containers 上の隔離 Linux 環境を、Workers から操作します。
プレビュー版ドキュメントとインストール済み @next 型を優先してください。 API は変更される可能性があります。このスキルはゲート、契約、および検索マップとして機能し、完全なマニュアルではありません。
新規プロジェクトにはこのラインを推奨します。デフォルトパッケージを使用しているアプリは sandbox-stable を使用してください。移行は、sandbox-migrate-to-next を使用して、依頼があった場合のみ行ってください。
1. ゲート — パッケージラインの確認
コードを作成する前に、アプリを検査してください：
| 確認項目 | 一致条件 |
|---|---|
| npm 依存関係 | @cloudflare/sandbox@next（またはその他のプレビュータグ） |
| コンテナイメージ | 同じライン（例：cloudflare/sandbox:next、next-python） |
| 見つけた場合… | 対応 |
|---|---|
デフォルトの @cloudflare/sandbox（@next なし） | 停止。 sandbox-stable を読み込んでください。このスキルの API を適用しないでください。 |
ユーザーが安定版から @next への移植を希望 | 停止。 sandbox-migrate-to-next を読み込んでください。 |
| セルフデプロイの ブリッジ のみ | ブリッジはまだ 1.0 プレビューラインにありません。ブリッジは安定版パッケージとイメージのままにしてください。ブリッジ（安定版） |
@next の Worker パッケージと安定版コンテナイメージを混在させないでください（その逆も同様）。
スキルのインストール: Agent セットアップ · cloudflare/skills
2. 契約 — 非妥協ルール
sandbox.exec(argv)は argv リストを受け取り、プロセスが 開始 された時点で解決します。終了したコマンド結果ではなく、ハンドル を返します。- 結果はハンドルのメソッドで収集します：
output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?)。 - 暗黙のシェルはありません。シェル構文を使用するには、明示的なシェルが必要です（例：
["/bin/bash", "-lc", script]）。 - 各起動は独立しています。ある
execでのcd/exportは次のexecには反映されません。起動ごとにcwdとenvを渡すか、1 つのシェルスクリプトを使用してください。 - プロセスハンドルには 標準入力がありません。対話的な使用 → ターミナル（
createTerminal+connect）。 - ローカルの待機
timeout/AbortSignalは 待機のみをキャンセル します。プロセスを強制終了しません。プロセスを強制終了するにはkillまたはexecのリモートtimeoutを使用してください。 getProcess/listProcesses/getTerminal/listTerminalsはコンテナを 起動しません。コンテナが起動していない場合はnull/[]を返します。- プロセス ID とターミナル ID は 現在のコンテナ に属し、サンドボックス ID に永続的に関連付けられるわけではありません。置き換え後も存続させる必要がある作業については、ID だけでなく、完全なジョブ（argv、cwd、env、アプリの状態）を保存してください。
- シークレット以外の設定のみを
setEnvVars/ 起動時のenvに格納します。ライブの認証情報は Worker 内に保持し、サンドボックスが外部 API を呼び出す場合はアウトバウンドハンドラを使用してください。 - 廃止された安定版 API（コア上の
gitCheckout、文字列exec完了、セッション実行、sandbox.terminal(request)）を 発明しないでください。 - すべてのエラーに同じ再試行ループを使用 しないでください（Errors ドキュメントを参照）。
最小限の形状：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode
タスク固有の API ドキュメント: references/api-quick-ref.md
サンプル一覧（next ブランチ）: references/examples.md
3. 検索 — タスクに応じたドキュメントを開く
実装する前にページを取得してください。インストール済みの @next 型が推測よりも優先されます。
| やりたいこと… | 開くドキュメント |
|---|---|
| 概要確認 / プレビュー選択 | 1.0 プレビュー概要 |
| 初めての Worker、wrangler、Dockerfile | はじめに |
exec、ハンドル、準備完了、耐久性 | プロセス実行 |
| プロセス API シグネチャ | プロセス API |
| サンドボックス ID とコンテナ、スリープ/破棄 | ライフサイクル |
cwd / env / setEnvVars | 環境変数 |
| 対話型 PTY / ブラウザターミナル | ターミナル · ターミナル API |
| Python/JS コードインタプリタ | インタプリタ · インタプリタ API |
| 拡張機能モデル | 拡張機能 |
| エラークラスとリカバリ | エラー · エラー API |
| よくある障害 | トラブルシューティング |
| API ハブ | API リファレンス |
ファイル、マウント、バックアップ、ポート、トンネル、proxyToSandbox | 共有サーフェスのメインドキュメント（安定版限定のセッション/トランスポート/sandbox.terminal は無視）: ファイル · ストレージ / マウント · ポート · トンネル · バックアップ · アウトバウンドトラフィック · サービス公開 · 本番デプロイ |
| サンプルアプリ | next のサンプル |
| まだ安定版パッケージを使用中 | sandbox-stable · メイン Sandbox ドキュメント |
| 既存の安定版アプリを移植する | sandbox-migrate-to-next · 移行ガイド |
4. リリース前の確認事項
- ロックファイルと Dockerfile が 同じ
@nextラインであること - インストール済みの
@next型に対して型チェックを行うこと - サンドボックス環境にライブのシークレットが含まれていないこと
- 本番プレビューのホスト名で特定の URL パターンを使用する場合は、カスタムドメインにワイルドカード DNS が必要