sandbox-next

Sandbox SDK — @next（1.0 プレビュー）

Workers から操作する、Cloudflare Containers 上の分離された Linux 環境です。

記憶に頼らず、プレビュー版ドキュメントとインストール済みの @next の型を優先してください。 API は変更されます。このスキルはゲートであり、契約であり、情報を探すためのマップであって、完全なマニュアルではありません。

新規プロジェクトには、このラインを推奨します。デフォルトのパッケージを引き続き使うアプリには sandbox-stable を使用してください。移行は、依頼された場合に限り sandbox-migrate-to-next を使ってください。

1. ゲート — パッケージのラインを確認する

コードを書く前に、アプリを確認してください。

確認項目	一致する必要がある内容
npm の依存関係	@cloudflare/sandbox@next（または別のプレビュータグ）
コンテナイメージ	同じライン（例：cloudflare/sandbox:next、next-python）

見つかったもの	対応
デフォルトの @cloudflare/sandbox（@next なし）	停止してください。 sandbox-stable を読み込んでください。このスキルの API は適用しないでください。
stable から @next への移行を希望している	停止してください。 sandbox-migrate-to-next を読み込んでください。
セルフデプロイした bridge のみ	bridge はまだ 1.0 プレビューラインではありません。bridge には stable パッケージとイメージを引き続き使用してください。Bridge（stable）

@next の Worker パッケージと stable のコンテナイメージ（またはその逆）を絶対に組み合わせないでください。

スキルのインストール：エージェントのセットアップ · cloudflare/skills

2. 契約 — 必ず守る事項

• sandbox.exec(argv) は argv リストを受け取り、プロセスの起動時に解決されます。完了したコマンド結果ではなく、ハンドルを返します。
• ハンドルのメソッドで結果を収集します：output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?)。
• シェルは暗黙的に使われません。シェル構文には、["/bin/bash", "-lc", script] のように明示的なシェルが必要です。
• 起動するたびに独立しています。ある exec 内の cd／export は、次の実行には引き継がれません。起動ごとに cwd と env を渡すか、1つのシェルスクリプトを使ってください。
• プロセスハンドルには stdin がありません。対話的に使う場合は、ターミナル（createTerminal + connect）を使用してください。
• ローカル待機の timeout／AbortSignal がキャンセルするのは待機のみです。プロセスは終了しません。kill または exec のリモート timeout を使用してください。
• getProcess／listProcesses／getTerminal／listTerminals はコンテナを起動しません。コンテナが起動していない場合、null／[] を返します。
• プロセス ID とターミナル ID は、サンドボックス ID に永久にひも付くのではなく、現在のコンテナに属します。置き換え後も保持する必要がある作業では、ID だけでなく、ジョブ全体（argv、cwd、env、アプリの状態）を保存してください。
• setEnvVars／起動時の env に設定するのは、シークレットではない設定のみです。認証情報は Worker 内に保持し、サンドボックスが外部 API を呼び出す場合はアウトバウンドハンドラーを使用してください。
• 削除された stable の API（core 上の 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 preview overview
最初の Worker、wrangler、Dockerfile	Get started
exec、ハンドル、準備状態、耐久性	Process execution
プロセス API のシグネチャ	Processes API
Sandbox ID とコンテナの違い、スリープ／破棄	Lifecycle
cwd／env／setEnvVars	Environment
インタラクティブ PTY／ブラウザーターミナル	Terminals · Terminals API
Python／JS コードインタープリター	Interpreter · Interpreter API
拡張機能のモデル	Extensions
エラークラスと復旧	Errors · Errors API
よくある失敗	Troubleshooting
API ハブ	API reference
ファイル、マウント、バックアップ、ポート、トンネル、proxyToSandbox	共通機能のメインドキュメント（stable 限定の session／transport／sandbox.terminal は対象外）：Files · Storage / mounts · Ports · Tunnels · Backups · Outbound traffic · Expose services · Production
サンプルアプリ	next のサンプル
まだ stable パッケージを使用している場合	sandbox-stable · Main Sandbox docs
既存の stable アプリを移行する場合	sandbox-migrate-to-next · Migrate

4. リリース前の確認事項

• ロックファイルと Dockerfile が同じ @next 系列であること
• インストール済みの @next の型で型チェックすること
• サンドボックス環境に有効なシークレットを置かないこと
• 本番のプレビューホスト名でこれらの URL パターンを使用する場合、カスタムドメインにワイルドカード DNS が必要です