sandbox-sdk

Cloudflare Sandbox SDK

Cloudflare Workers 上で、安全に分離されたコード実行環境を構築します。

最初に：インストールを確認する

npm install @cloudflare/sandbox
docker info  # Must succeed - Docker required for local dev

情報の取得元

Sandbox SDK に関する知識は古くなっている可能性があります。Sandbox SDK に関する作業では、事前学習よりも情報の取得を優先してください。

リソース	URL
ドキュメント	https://developers.cloudflare.com/sandbox/
API リファレンス	https://developers.cloudflare.com/sandbox/api/
サンプル	https://github.com/cloudflare/sandbox-sdk/tree/main/examples
はじめに	https://developers.cloudflare.com/sandbox/get-started/

機能を実装する際は、まず該当するドキュメントページまたはサンプルを取得してください。

必須の設定

wrangler.jsonc（正確な内容です。構造を変更しないでください）：

{
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",
    "max_instances": 1
  }],
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

Worker エントリーポイント - Sandbox クラスを再エクスポートする必要があります：

import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';  // Required export

クイックリファレンス

タスク	メソッド
サンドボックスを取得	getSandbox(env.Sandbox, 'user-123')
コマンドを実行	await sandbox.exec('python script.py')
コードを実行（インタープリター）	await sandbox.runCode(code, { language: 'python' })
ファイルを書き込む	await sandbox.writeFile('/workspace/app.py', content)
ファイルを読み込む	await sandbox.readFile('/workspace/app.py')
ディレクトリを作成	await sandbox.mkdir('/workspace/src', { recursive: true })
ファイルを一覧表示	await sandbox.listFiles('/workspace')
ポートを公開	await sandbox.exposePort(8080)
破棄	await sandbox.destroy()

主なパターン

コマンドを実行する

const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }

コードインタープリター（AI に推奨）

豊富な出力を得るには、LLM が生成したコードの実行に runCode() を使用します：

const ctx = await sandbox.createCodeContext({ language: 'python' });

await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx });
const result = await sandbox.runCode('sum(data)', { context: ctx });
// result.results[0].text = "6"

言語：python、javascript、typescript

状態はコンテキスト内で保持されます。本番環境では明示的にコンテキストを作成してください。

ファイル操作

await sandbox.mkdir('/workspace/project', { recursive: true });
await sandbox.writeFile('/workspace/project/main.py', code);
const file = await sandbox.readFile('/workspace/project/main.py');
const files = await sandbox.listFiles('/workspace/project');

用途に応じた使い分け

必要な処理	使用するもの	理由
シェルコマンド、スクリプト	exec()	直接制御、ストリーミング
LLM が生成したコード	runCode()	豊富な出力、状態の保持
ビルド／テストパイプライン	exec()	終了コード、標準エラーの取得
データ分析	runCode()	グラフ、テーブル、pandas

Dockerfile の拡張

ベースイメージ（docker.io/cloudflare/sandbox:0.7.0）には、Python 3.11、Node.js 20、および一般的なツールが含まれています。

Dockerfile を拡張して依存関係を追加します：

FROM docker.io/cloudflare/sandbox:0.7.0

# Python packages
RUN pip install requests beautifulsoup4

# Node packages (global)
RUN npm install -g typescript

# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # Required for local dev port exposure

イメージは軽量に保ってください。コールドスタート時間に影響します。

プレビュー URL（ポートの公開）

サンドボックス内で実行されている HTTP サービスを公開します：

const { url } = await sandbox.exposePort(8080);
// Returns preview URL for the service

本番環境での要件：プレビュー URL には、ワイルドカード DNS（*.yourdomain.com）を設定したカスタムドメインが必要です。.workers.dev ドメインでは、プレビュー URL のサブドメインはサポートされていません。

こちらを参照してください：https://developers.cloudflare.com/sandbox/guides/expose-services/

OpenAI Agents SDK との統合

SDK には、@cloudflare/sandbox/openai で OpenAI Agents 用のヘルパーが用意されています：

import { Shell, Editor } from '@cloudflare/sandbox/openai';

統合パターンの全体像については、examples/openai-agents を参照してください。

サンドボックスのライフサイクル

• getSandbox() はすぐに戻ります。コンテナは最初の操作時に遅延起動します
• コンテナは非アクティブな状態が 10 分続くとスリープします（sleepAfter で設定可能です）
• リソースをすぐに解放するには、destroy() を使用します
• 同じ sandboxId には常に同じサンドボックスインスタンスが返されます

アンチパターン

• 内部クライアント（CommandClient、FileClient）を使用しないでください - sandbox.* メソッドを使用してください
• Sandbox のエクスポートを省略しないでください - export { Sandbox } がないと Worker をデプロイできません
• 複数ユーザー向けにサンドボックス ID をハードコードしないでください - ユーザーまたはセッションの識別子を使用してください
• クリーンアップを忘れないでください - 一時的なサンドボックスでは destroy() を呼び出してください

詳細なリファレンス

• references/api-quick-ref.md - オプションと戻り値の型を含む API 全体
• references/examples.md - ユースケース別のサンプル一覧