sandbox-stable

Sandbox SDK — 安定版パッケージ

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

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

この項目は、npm の現在の安定版デフォルトパッケージです。メインの Sandbox ドキュメントで説明されています。既存のアプリはこのまま使い続け、リリースを続けられます。

新しいプロジェクトには、sandbox-next と併せて @cloudflare/sandbox@next をおすすめします。可能であれば、1.0 が安定版リリースになるときに備え、sandbox-migrate-to-next を使った移行を計画してください。ユーザーから依頼されない限り、無理に移行しないでください。

1. ゲート — パッケージの系統を確認する

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

確認項目	一致すべき内容
npm の依存関係	デフォルトの @cloudflare/sandbox（@next やプレビュータグではないこと）
コンテナイメージ	対応する安定版イメージ（cloudflare/sandbox:next ではないこと）

見つかったもの…	対応
@cloudflare/sandbox@next または next イメージ	中止してください。 sandbox-next を読み込んでください。
ユーザーが 1.0 / @next への移行を希望している	中止してください。 sandbox-migrate-to-next を読み込んでください。安定版パッケージにプレビュー API を一部だけ適用しないでください。
非推奨の安定版 API の整理のみ	このページの範囲です。2026 deprecation guide を使用してください。これは @next への移行ではありません。

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

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

2. 契約 — 必須事項

• await sandbox.exec(command) はコマンド文字列を受け取り、コマンドの完了時に、バッファーされた stdout / stderr / exitCode（および関連フィールド）とともに解決します。
• 長時間実行やストリーミングの処理には、安定版のコマンド API（startProcess、execStream および関連ヘルパー）を使用してください。@next の単一ハンドルモデルは使用しないでください。Commands ドキュメントを開き、安定版で @next の output() ハンドルを作らないでください。
• セッションでは、コマンド間で作業ディレクトリや環境を保持できます（デフォルトセッション / enableDefaultSession、createSession）。呼び出し間で状態を引き継ぐ必要がある場合は、Sessions ドキュメントを参照してください。
• インタラクティブなブラウザーターミナルでは、安定版の sandbox.terminal(request) とセッション / xterm ヘルパーを使用することがよくあります。パッケージが @next でない限り、プレビュー版の createTerminal は使用しないでください。
• トンネルや大容量のバイナリストリーミングには、RPC トランスポートを優先してください。HTTP/WebSocket トランスポートは非推奨です（下記のクリーンアップガイドを参照）。
• ファイル、マウント、ポート、トンネル、バックアップ、ライフサイクル、インタープリターについては、シグネチャをメインドキュメントで確認し、インストール済みの安定版の型を信頼してください。
• 秘密情報ではない設定はサンドボックス環境に置き、実際の認証情報は Worker に置いてください。プロセスが外部 API を呼び出す場合は、アウトバウンドハンドラーを使用してください。
• URL パターンでカスタムドメインを使用する場合、本番のプレビュー用ホスト名にはワイルドカード DNS が必要です。
• 依存関係が安定版のままである間は、@next の argv / process.output() API を適用しないでください。
• 自分でデプロイした bridge は、安定版パッケージとイメージを使い続けてください。Bridge

最小構成：

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、ストリーミング、バックグラウンドプロセス	Commands API · コマンドを実行する · バックグラウンドプロセス · 出力のストリーミング
コマンド間でのセッション／シェル状態	セッションの概念 · Sessions API
getSandbox のオプション、スリープ、破棄	Lifecycle API · Sandbox のオプション
環境変数	環境変数
ファイル	Files API · ファイルを管理する · ファイル監視
バケット／マウント	Storage API · バケットをマウントする
バックアップ	Backups API · バックアップと復元
ポート、プレビュー URL、公開	Ports API · サービスを公開する
トンネル	Tunnels API
プロキシ／Workers 接続	リクエストをプロキシする · Workers 接続
ブラウザー／PTY ターミナル	Terminal API · ターミナルの概念 · ブラウザーターミナル
コードインタープリター	Interpreter API · コード実行
サンドボックス内の Git	Git ワークフロー
シークレット／エグレス	アウトバウンドトラフィック
WebSocket	WebSocket 接続
Docker-in-Docker	Docker in Docker
本番環境へのデプロイ	本番環境へのデプロイ
コンテナーの概念	コンテナー
ハウツーの一覧	ガイド
API の一覧	API リファレンス
安定版を使い続ける場合の非推奨 API	2026 年の非推奨化ガイド
セルフデプロイ型ブリッジ	ブリッジ · Bridge HTTP API
サンプル（安定版／main）	GitHub のサンプル
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 を使用してください。促されていないのに強制的に切り替えないでください