sandbox-sdk

Cloudflare Sandbox SDK

在 Cloudflare Workers 上建立安全、隔離的程式碼執行環境。

第一步：確認安裝

npm install @cloudflare/sandbox
docker info  # 必須成功 - 本機開發需要 Docker

檢索來源

你對 Sandbox SDK 的知識可能已過時。對於任何 Sandbox SDK 任務，優先檢索而非預先訓練。

資源	網址
文件	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';  // 必要匯出

快速參考

任務	方法
取得沙箱	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）

使用 runCode() 執行 LLM 生成的程式碼，並獲得豐富的輸出：

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

狀態在 context 內持續存在。正式環境請建立明確的 context。

檔案操作

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');

何時使用何種方法

需求	使用	原因
Shell 指令、腳本	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 套件
RUN pip install requests beautifulsoup4

# Node 套件（全域）
RUN npm install -g typescript

# 系統套件
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # 本機開發連接埠暴露所需

保持映像輕量 - 會影響冷啟動時間。

預覽網址（連接埠暴露）

暴露沙箱中執行的 HTTP 服務：

const { url } = await sandbox.exposePort(8080);
// 回傳服務的預覽網址

正式環境需求：預覽網址需要具有萬用字元 DNS（*.yourdomain.com）的自訂網域。.workers.dev 網域不支援預覽網址子網域。

請參閱：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 - 範例索引含使用案例