mcpField
S
sandbox-sdk

sandbox-sdk

github.com/cloudflare開発5.4k41 回インストール今日更新
リポジトリ

sandbox-sdk について

sandbox-sdk は、Cloudflare Workers 上で Cloudflare Sandbox SDK を使った隔離コード実行環境の構築を支援するスキルです。環境設定、コード実行、ファイル操作、ライフサイクル管理を扱います。

主な機能

  1. 01シェルコマンドとスクリプトの実行
  2. 02Python、JavaScript、TypeScript の実行
  3. 03ファイルとディレクトリの管理
  4. 04プレビュー URL によるサンドボックスサービスの公開
  5. 05ライフサイクルとクリーンアップの設定

活用シーン

  1. 01隔離環境で LLM 生成コードを実行
  2. 02サンドボックスでスクリプトを構築・テスト
  3. 03プロジェクトファイルの読み書き
  4. 04サンドボックス内の HTTP サービスを公開

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cloudflare/cloudflare-docs --skill sandbox-sdk

インストール後、Claude Code で/sandbox-sdkを入力して読み込まれたか確認します。

同梱ファイルreferences/api-quick-ref.mdreferences/examples.md

詳細

Cloudflare Sandbox SDK

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

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

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

検索を優先した開発

重要：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()終了コード、stderr の取得
データ分析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() を呼び出します

詳細リファレンス

コメント

Markdown 対応