Sandbox SDK — 安定版パッケージ
Cloudflare Containers上の隔離Linux環境。Workersから駆動します。
メインのSandboxドキュメントとインストール済みの安定版型定義を記憶より優先してください。 このスキルはゲート、契約、参照マップであり、完全なマニュアルではありません。
この行は現在の安定版デフォルトnpmパッケージです。メインのSandboxドキュメントに記載されています。既存のアプリはここに留まり、そのままリリースを続けられます。
新規プロジェクトには@cloudflare/sandbox@nextと**sandbox-nextをお勧めします。可能であればsandbox-migrate-to-next**を使って移行を計画し、1.0が安定版リリースになったときに備えてください。ユーザーが要求しない限り、その移行を強制しないでください。
1. ゲート — パッケージラインの確認
コードを書く前に、アプリを検査してください：
| チェック項目 | 一致条件 |
|---|---|
| npm依存関係 | デフォルトの@cloudflare/sandbox（@next / プレビュータグではない） |
| コンテナイメージ | 対応する安定版イメージ（cloudflare/sandbox:nextではない） |
| 発見した場合… | アクション |
|---|---|
@cloudflare/sandbox@next または nextイメージ | 停止。 **sandbox-next**を読み込んでください。 |
ユーザーが1.0 / @nextへの移植を希望 | 停止。 **sandbox-migrate-to-next**を読み込んでください。安定版パッケージにプレビューAPIを中途半端に適用しないでください。 |
| 廃止予定の安定版APIのクリーンアップのみ | ここに留まり、2026年廃止ガイドを使用してください。これは@nextへの移行ではありません。 |
安定版のWorkerパッケージと@nextコンテナイメージを混在させないでください（またはその逆）。
スキルのインストール：エージェント設定 · cloudflare/skills
2. 契約 — 非妥協ルール
await sandbox.exec(command)はコマンド文字列を受け取り、コマンドが終了したときに、バッファリングされたstdout/stderr/exitCode（および関連フィールド）とともに解決します。- 長時間実行やストリーミング処理には安定版のコマンドAPI（
startProcess、execStream、および関連ヘルパー）を使用します。@nextのシングルハンドルモデルは使用しません。コマンドドキュメントを開き、安定版で@nextのoutput()ハンドルを発明しないでください。 - セッションは、コマンド間で作業ディレクトリと環境を保持できます（デフォルトセッション /
enableDefaultSession、createSession）。状態を呼び出し間で引き継ぐ必要がある場合は、セッションドキュメントを参照してください。 - インタラクティブブラウザターミナルは、多くの場合、安定版では**
sandbox.terminal(request)**とセッション/xtermヘルパーを使用します。パッケージが@nextでない限り、プレビュー版のcreateTerminalは使用しません。 - トンネルや大規模/バイナリストリーミングを使用する場合は、RPCトランスポートを推奨します。HTTP/WebSocketトランスポートは非推奨です（以下のクリーンアップガイドを参照）。
- ファイル、マウント、ポート、トンネル、バックアップ、ライフサイクル、インタプリタ：シグネチャについてはメインドキュメントを使用し、インストール済みの安定版型定義を信頼してください。
- シークレット以外の設定はサンドボックス環境に、ライブ認証情報はWorkerに配置します。プロセスが外部APIを呼び出す場合は出力ハンドラを使用します。
- 本番プレビューホスト名には、それらのURLパターンを使用する場合、カスタムドメインにワイルドカードDNSが必要です。
- 依存関係が安定版のままである間は、
@nextのargv/process.output()APIを適用しないでください。 - 自己デプロイ型ブリッジは、安定版パッケージとイメージに留まります。ブリッジ
最小限の形状：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success
3. 参照 — タスクに応じたドキュメントを開く
実装前にページを取得してください。インストール済みの安定版型定義が推測より優先されます。
| 必要な操作… | 開くドキュメント |
|---|---|
| 概要把握 | Sandbox概要 |
| 初めてのWorker、テンプレート、Docker | はじめに |
exec、ストリーミング、バックグラウンドプロセス | コマンドAPI · コマンド実行 · バックグラウンドプロセス · 出力ストリーミング |
| セッション / コマンド間のシェル状態 | セッションの概念 · セッションAPI |
getSandboxオプション、スリープ、破棄 | ライフサイクルAPI · Sandboxオプション |
| 環境変数 | 環境変数 |
| ファイル | ファイルAPI · ファイル管理 · ファイル監視 |
| バケット / マウント | ストレージAPI · バケットマウント |
| バックアップ | バックアップAPI · バックアップと復元 |
| ポート、プレビューURL、公開 | ポートAPI · サービスの公開 |
| トンネル | トンネルAPI |
| プロキシ / Workers接続 | プロキシリクエスト · Workers接続 |
| ブラウザ / PTYターミナル | ターミナルAPI · ターミナルの概念 · ブラウザターミナル |
| コードインタプリタ | インタプリタAPI · コード実行 |
| サンドボックス内のGit | Gitワークフロー |
| シークレット / 外部通信 | 外部トラフィック |
| WebSocket | WebSocket接続 |
| Docker-in-Docker | Docker in Docker |
| 本番デプロイ | 本番デプロイメント |
| コンテナの概念 | コンテナ |
| ハウツー索引 | ガイド |
| API索引 | APIリファレンス |
| 安定版に留まりつつ廃止予定のAPI | 2026年廃止ガイド |
| 自己デプロイ型ブリッジ | ブリッジ · ブリッジHTTP API |
例（安定版/main） | GitHub上のexamples |
| 1.0プレビューでの新規作業 | sandbox-next · 1.0プレビュー |
既存アプリを@nextに移植 | sandbox-migrate-to-next · 移行 |
廃止予定APIのクリーンアップ（安定版に留まる）
まずパッケージと対応するイメージを更新し、その後ガイドに従ってください。典型的な検索：
rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'
このパスでは@nextに切り替わりません。
4. リリース前の確認
- Workerパッケージとコンテナイメージが同じ安定版ラインであること
- インストール済みの安定版型定義に対して型チェックが通ること
- サンドボックス環境にライブシークレットがないこと
- 非推奨のトランスポート/ヘルパーを使用している場合は、2026年廃止のクリーンアップを完了または追跡すること
- チームが1.0への準備ができたら、**
sandbox-migrate-to-next**を使用してください。促されずに強制カットオーバーを行わないでください。