サンドボックスは、コードを実行する分離された実行環境です。各サンドボックスには次の特徴があります。
- 一意の識別子（サンドボックス ID）がある
- 分離されたファイルシステムを持つ
- 専用の Linux コンテナで動く
- コンテナが稼働しているあいだ状態を保つ
- Cloudflare Durable Object として存在する
サンドボックスは、その ID を初めて参照したときに作成されます。
const sandbox = getSandbox(env.Sandbox, "user-123");
await sandbox.exec('echo "Hello"'); // First request creates sandboxサンドボックスのコンテナが稼働し、リクエストを処理しています。ファイル、実行中のプロセス、シェルセッション、環境変数など、すべての状態が使えます。
一定時間操作がないと（デフォルトは 10 分。sleepAfter で変更できます）、コンテナはリソースを解放するために停止します。次のリクエストが来ると、新しいコンテナが起動します。以前の状態はすべて失われ、環境は初期状態に戻ります。
注: keepAlive: true のコンテナは Idle 状態になりません。30 秒ごとにハートビートの ping を送り、追い出しを防ぎます。
サンドボックスは明示的に破棄するか、自動でクリーンアップされます。
await sandbox.destroy();
// All files, processes, and state deleted permanentlyサンドボックスの状態は、コンテナが稼働しているあいだだけ存在します。信頼性の高いアプリケーションを作るには、この点を押さえておく必要があります。
コンテナが稼働しているあいだ（通常は数分から数時間のアクティビティ）:
/workspace、/tmp、/homeに書いたファイルはそのまま使えます- バックグラウンドプロセスは動き続けます
- シェルセッションは作業ディレクトリと環境を保ちます
- コードインタープリターのコンテキストは変数と import を保持します
コンテナが停止したとき（無操作または明示的な破棄）:
- ファイルはすべて削除されます
- プロセスはすべて終了します
- シェルの状態はすべて初期化されます
- コードインタープリターのコンテキストはすべてクリアされます
次のリクエストでは、きれいな環境の新しいコンテナが作成されます。
const sandbox = getSandbox(env.Sandbox, `user-${userId}`);対話環境、プレイグラウンド、ノートブックなど、各ユーザーが自分の稼働中ワークスペースに戻る用途に向いています。
const sessionId = `session-${Date.now()}-${Math.random()}`;
const sandbox = getSandbox(env.Sandbox, sessionId);
// Later:
await sandbox.destroy();一度きりの実行、CI/CD、きれいな環境が必要なテストに向いています。
const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commit}`);タスクとサンドボックスの対応がはっきりした、べき等な処理向きです。ビルド、パイプライン、バックグラウンドジョブに適しています。
サンドボックスへの最初のリクエストが、地理的な配置を決めます。以降のリクエストは同じ場所へ送られます。
グローバルなアプリの場合:
- 選択肢 1: ユーザーごとに、リージョン接尾辞付きの複数サンドボックス（
user-123-us、user-123-eu） - 選択肢 2: ユーザーあたり 1 つのサンドボックス（単純ですが、一部のユーザーでレイテンシが高くなります）
try {
const sandbox = getSandbox(env.Sandbox, sessionId);
await sandbox.exec("npm run build");
} finally {
await sandbox.destroy(); // Clean up temporary sandboxes
}破棄する場合: セッション終了、タスク完了、リソースが不要になったとき
破棄しない場合: 個人用環境、長時間稼働するサービス
keepAlive: true のコンテナは自動でタイムアウトしないため、明示的に管理します。
const sandbox = getSandbox(env.Sandbox, 'persistent-task', {
keepAlive: true
});
// Later, when done with long-running work
await sandbox.setKeepAlive(false); // Allow normal timeout behavior
// Or explicitly destroy:
await sandbox.destroy();コンテナは無操作や障害のあと再起動します。状態喪失を前提にアプリケーションを設計します。
// Check if required files exist before using them
const files = await sandbox.listFiles("/workspace");
if (!files.includes("data.json")) {
// Reinitialize: container restarted and lost previous state
await sandbox.writeFile("/workspace/data.json", initialData);
}
await sandbox.exec("python process.py");SDK は、npm パッケージのバージョンと Docker コンテナイメージのバージョンが一致するかを自動で確認します。バージョンがずれると、機能が壊れたり、想定外の動きをしたりします。
動作:
- サンドボックス起動時に、SDK はコンテナのバージョンを問い合わせます
- バージョンが一致しない場合は警告がログに出ます
- 互換性がないと、一部の機能が正しく動かないことがあります
警告が出る場面:
- npm パッケージを更新した（
npm install @cloudflare/sandbox@latest）が、Dockerfile のFROM行を更新し忘れた
直し方:
Dockerfile を npm パッケージのバージョンに合わせます。例: @cloudflare/sandbox@0.7.0 の場合:
# Default image (JavaScript/TypeScript)
FROM docker.io/cloudflare/sandbox:0.7.0
# Or Python image if you need Python support
FROM docker.io/cloudflare/sandbox:0.7.0-pythonイメージのバリアントとベースイメージの拡張については、Dockerfile リファレンス を参照してください。
- 一貫した名前 - わかりやすく、予測しやすい命名規則を使います
- 一時サンドボックスは片付ける - 使い終わったら必ず破棄します
- ユーザーのワークスペースは再利用する - ユーザーあたり 1 つの長寿命サンドボックスで足りることが多いです
- 操作をまとめる - コマンドを結合します:
npm install && npm test && npm build - 状態は一時的だと想定する - コンテナは無操作のあと再起動し、状態はすべて失われます
- アーキテクチャ - システム内でのサンドボックスの位置づけ
- コンテナランタイム - サンドボックス内部で動くもの
- セッション管理 - より高度な状態の分離
- ディレクトリのバックアップ - 復元したファイルがスリープ後に残らない理由（再復元が必要）
- Lifecycle API - サンドボックスの作成と管理
- Sessions API - 実行セッションの作成と管理