CloudflareのSandbox SDKを試してみた

https://workers-tech.connpass.com/event/365623/

Transcript

1. CloudflareのSandbox SDKを試してみた syumai Cloudflare Workers Tech Talks in Fukuoka #1 (2025/11/12)
2. 自己紹介 syumai ECMAScript 仕様輪読会 / Asakusa.go 主催 Software Design 2023年12月号から2025年2月号まで Cloudflare Workersの連載をしました Twitter (現𝕏): @__syumai Website: https://syum.ai
3. 本日話すこと CloudflareのSandbox SDKとは？ Sandbox SDKで何ができるのか？ 基本操作、その他の使える機能 Sandboxのプロジェクト構成 最小限のテンプレートのプロジェクト構成 コンテナのエントリポイントについて 応用例 好きなコマンドの追加 使ってみた感想
4. ※注意 発表者もまだSandbox SDKを使いこなせていません ドキュメントを読み飛ばしたりしているので、本発表の内容には恐らく抜け漏れ があります Sandbox SDKはまだベータ版なので、今後APIが変わる可能性があります
5. CloudflareのSandbox SDKとは？
6. https://sandbox.cloudflare.com/
7. CloudflareのSandbox SDKとは？ Cloudflareの基盤上で信頼できないコード / コマンドの実行に使えるSandboxを操 作するためのSDK Cloudflare Sandboxという独立したサービスは無い。SDKの名前 Sandboxは、Linux環境として動作する Cloudflare Containersベース ということでDurable Objectsも使う 呼び出しは普段通り、Cloudflare Workers経由 SDKはJavaScript / TypeScriptのみ提供 現在Cloudflareの有料プランで利用可能
8. Sandbox SDKで何ができるのか？
9. 公式ドキュメントの説明 (Google翻訳) Containers上に構築されたSandbox SDKは、コマンドの実行、ファイルの管理、 バックグラウンドプロセスの実行、サービスの公開など、 Workersアプリケーシ ョンからの操作を可能にするシンプルなAPIを提供します。 サンドボックスは、コード実行を必要とするAIエージェント、インタラクティブ 開発環境、データ分析プラットフォーム、CI/CDシステム、そしてエッジでの安 全なコード実行を必要とするあらゆるアプリケーションの構築に最適です。 https://developers.cloudflare.com/sandbox/ → 単なるWebアプリケーションに閉じない、広いユースケースが想定されている
10. 基本操作 1. コマンド実行 2. コード実行 3. ファイル操作
11. コマンド実行 https://developers.cloudflare.com/sandbox/ より引用
12. コード実行 (Python, JS, TSのみ対応) https://developers.cloudflare.com/sandbox/ より引用
13. ファイル操作 https://developers.cloudflare.com/sandbox/ より引用
14. コード実行 (runCode) とコマンド実行 (exec) の違い コード実行は、実行コンテキストを使い回せる createCodeContext で生成したコンテキスト上でコード実行することで、状 態を維持しつつ連続してコード実行できる 事前にセットアップした変数、関数などの宣言を使って、コード実行したい パターンなどで有効
15. コード実行 (runCode) とコマンド実行 (exec) の違い コード実行の方が、リッチな結果を扱いやすい コマンド実行は、基本的にテキストの結果を前提としている (補足: ストリームで結果を返すオプションもある) コード実行を使うと結果として画像などを返しやすい グラフの生成などで有効
16. https://developers.cloudflare.com/sandbox/api/interpreter/#rich-output-formats
17. その他の機能 プレビューURLの発行 WebSocketの利用 Git checkout などがあります
18. プレビューURLの発行 exposePort でコンテナのポートを公開すると、それに対応するプレビューURL が発行される コンテナ内で動くWebアプリケーションのプレビューなどに使える https://developers.cloudflare.com/sandbox/concepts/preview-urls/
19. https://developers.cloudflare.com/sandbox/concepts/preview-urls/
20. Sandboxのプロジェクト構成
21. 最小限のテンプレートの構成 sandbox-sdkリポジトリ内のテンプレートからプロジェクトを作成できる https://developers.cloudflare.com/sandbox/get-started/ $ npm create cloudflare@latest -- my-sandbox \ --template=cloudflare/sandbox-sdk/examples/minimal プロジェクトを作成したら、そのまま npm run deploy でデプロイ完了します！
22. 最小限のテンプレートの構成 src/index.ts Sandboxを起動するWorkerのファイル Dockerfile Sandboxのコンテナのイメージを作る ためのファイル これはSDKでよしなにやってくれない ので、自分で置かないといけない wrangler.jsonc Containerの設定などが入っている https://github.com/cloudflare/sandbox- sdk/tree/main/examples/minimal
23. src/index.ts コード実行・ファイル操作の簡単な例が入っている
24. https://github.com/cloudflare/sandbox-sdk/blob/main/examples/minimal/src/index.ts
25. https://github.com/cloudflare/sandbox-sdk/blob/main/examples/minimal/src/index.ts
26. Dockerfile Docker Hubで配布されているSandbox SDKのbase imageを指定するだけの Dockerfileが置かれている このbase imageの中身については後ほど見ます https://github.com/cloudflare/sandbox-sdk/blob/main/examples/minimal/Dockerfile
27. wrangler.jsonc Sandboxのコンテナの起動設定や、 Durable Objectsの設定が書かれている minimalのテンプレートだと、instance typeは lite の指定になっている https://github.com/cloudflare/sandbox- sdk/blob/main/examples/minimal/wrangler.jso nc
28. Sandboxのエントリポイントを追ってみる
29. cloudflare/sandbox-sdk のリポジトリ構成 cloudflare/sandbox-sdkは、モノレポ構成になっている packages/sandbox @cloudflare/sandbox packageとしてnpmで配布されている部分 Worker側で動くコード Dockerfileもこちらに設置されている packages/sandbox-container Container内で動くコード TypeScript製のHTTPサーバーとして実装されている
30. コンテナのハンドラ (sandbox-container/src/handlers/execute-handler.ts) 各機能が愚直にHTTPハンドラとして実装されている (フレームワークは使っていない) export class ExecuteHandler extends BaseHandler<Request, Response> { // ... async handle(request: Request, context: RequestContext): Promise<Response> { const url = new URL(request.url); const pathname = url.pathname; switch (pathname) { case '/api/execute': return await this.handleExecute(request, context); case '/api/execute/stream': return await this.handleStreamingExecute(request, context); https://github.com/cloudflare/sandbox-sdk/blob/main/packages/sandbox- container/src/handlers/execute-handler.ts
31. コンテナのエントリポイント (sandbox-container/src/index.ts) 実はBun.serveで実装されている // Start the Bun server const server = serve({ idleTimeout: 255, fetch: app.fetch, hostname: '0.0.0.0', port: 3000, // Enhanced WebSocket placeholder for future streaming features websocket: { async message() { // WebSocket functionality can be added here in the future } } }); https://github.com/cloudflare/sandbox-sdk/blob/main/packages/sandbox- container/src/index.ts
32. コンテナのエントリポイント (sandbox/Dockerfile) OSはUbuntu 22.04 途中のステップでBunを入手して、最後にstartup.shを実行 # ============================================================================ # Stage 5: Runtime - Ubuntu 22.04 with only runtime dependencies # ============================================================================ FROM ubuntu:22.04 AS runtime # ... # Install Bun runtime from official image COPY --from=oven/bun:1 /usr/local/bin/bun /usr/local/bin/bun # ... # Use startup script CMD ["/container-server/startup.sh"] https://github.com/cloudflare/sandbox-sdk/blob/main/packages/sandbox/Dockerfile
33. コンテナのエントリポイント (sandbox/startup.sh) startup.shは、コンテナのHTTPサーバーをBunで起動する #!/bin/bash exec bun /container-server/dist/index.js https://github.com/cloudflare/sandbox-sdk/blob/main/packages/sandbox/startup.sh
34. コンテナで使えるコマンドについて Node.js ( npm, npx ), Python ( python3, pip3 )をランタイムで使えるように Dockerfileで設定されている Pythonについては、 matplotlib numpy pandas ipython を事前導入済み もちろん bun コマンドも使える その他、 apt-get で以下のコマンド等をインストールしている curl, wget, git, unzip, zip, jq これらを exec で利用可能
35. 応用例
36. 好きなコマンドの追加 base imageがただのUbuntuなので、Dockerfileを書き換えれば好きなコマンドを足 せる これを利用して、 go run をSandboxで使えるようにしてみました https://github.com/syumai/workers-playground/tree/main/sandbox-go- playground
37. Dockerfileの修正 go コマンドを exec で呼べるようにしたかった → go コマンドのバイナリをDLするか、 apt-get で入手する 手元 (arm64) とCloudflare Containers (amd64) でアーキテクチャが違う バイナリのURLをアーキテクチャごとに分岐するのが面倒 → apt-get で入手することに ただ、Ubuntu 22.04の go は1.18系とかなり古い 1.25が使いたかったので、aptのリポジトリを追加してインストールした
38. Dockerfileの修正 install / cleanでステップを分けるとimageサイズが2000MB制限を超えてしまった ので無理矢理まとめた (もっといい方法があるかも) FROM docker.io/cloudflare/sandbox:0.4.18 RUN apt-get update && \ apt-get install -y --no-install-recommends \ software-properties-common gnupg && \ add-apt-repository ppa:longsleep/golang-backports && \ apt-get update && \ apt-get install -y --no-install-recommends \ golang-1.25-go && \ apt-get remove -y software-properties-common gnupg && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* RUN ln -s /usr/lib/go-1.25/bin/go /usr/bin/go # ... 以下修正なし
39. Workerの修正 ここまでできたら、 exec で普通に go run が使えます // Execute Go code if (url.pathname === '/run') { await sandbox.writeFile('/workspace/main.go', `package main import ( "fmt" "time" ) func main() { fmt.Printf("Hello, World! %s\\n", time.Now().Format(time.RFC3339)) }`); const result = await sandbox.exec('go run /workspace/main.go'); https://github.com/syumai/workers-playground/blob/main/sandbox-go- playground/src/index.ts
40. go コマンドの追加で詰まったポイント コンテナイメージの2000MB制限に簡単に引っかかった apt-get を使わずにバイナリのコピーで済むならその方がイメージサイズを 小さくできそう ただ、手元の環境とCloudflare Containerでアーキテクチャがズレる場合 のDockerfileの書き方が面倒そう (意外とそうでもないかも？)
41. go コマンドの追加で詰まったポイ ント Containerのインスタンスのスペック不足 lite だとどれだけ待っても go run が動いてくれなかった basic に変えたら動いた https://developers.cloudflare.com/contain ers/pricing/
42. デモ 今紹介した内容の応用で、SandboxでGoのコードを実行するMCPサーバーを作っ たのでデモします！ https://github.com/syumai/workers-playground/tree/main/go-sandbox-mcp
44. Sandbox SDKを使ってみた感想
45. Sandbox SDKを使ってみた感想 インスタンスのプロビジョニングにそこそこ時間がかかる 正確に計測していないが、1分レベルで待つこともある印象 リクエストの度にインスタンスをプロビジョニングするのは厳しそう リクエストの度にプロビジョニングしないとなると、インスタンスの使い回 しが前提となる Sandboxでファイルシステムへのアクセスを許容する場合、使い回した インスタンスの状態が他のユーザーに影響しうる これはインスタンスが使い捨てなら考慮不要だった
46. 誰のためのSandboxか？ 不特定多数のユーザーに任意コード実行させるのはメインのユースケースではな さそう インスタンスにアクセスできるユーザーを制限できるならこの使い方もあり かもしれない ただ、ユーザーにファイルシステムへのアクセスを許容すると、破壊さ れたインスタンスの修復について考えないといけない または、インスタンスで実行できるコードを制限できるならあり Webアプリケーションのプレビュー用など
47. 誰のためのSandboxか？ Sandboxとは言っても、基本的には不特定多数ではなく、個人、または自分の組 織で安心して使えるSandboxくらいの位置付けが適切そう もっと使い込んでみて、改めて結論を出したい
48. まとめ CloudflareのSandboxは、独立したサービスではなくてSDK Cloudflare Containersベースの仕組み このSDKで、Sandbox内のコマンド実行、コード実行、ファイル操作などができる SandboxのコンテナはUbuntu 22.04で、エントリポイントにBunを使っている 足したいコマンドがあったら、Dockerfileを変更すれば追加可能 インスタンスのプロビジョニングのコストが大きく、インスタンスの使い回しに ついて考慮が必要そう
49. ご清聴ありがとうございました！