sandbox-sdk
Build sandboxed applications for secure code execution. Load when building AI code execution, code interpreters, CI/CD systems, interactive dev environments, or executing untrusted code. Covers Sandbox SDK lifecycle, commands, files, code interpreter, and preview URLs. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
- License 许可
- MIT
- 最近更新
- 2026-07-19
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- sandbox-sdk
- description
- Build sandboxed applications for secure code execution. Load when building AI code execution, code interpreters, CI/CD systems, interactive dev environments, or executing untrusted code. Covers Sandbox SDK lifecycle, commands, files, code interpreter, and preview URLs. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
02 资源文件 3
- 参考文档agents/openai.yaml102 B
- 参考文档references/api-quick-ref.md3.1 KB
- 参考文档references/examples.md1.5 KB
03 SKILL.md 正文
Cloudflare Sandbox SDK
Build secure, isolated code execution environments on Cloudflare Workers.
FIRST: Verify Installation
npm install @cloudflare/sandbox
docker info # Must succeed - Docker required for local dev
Retrieval Sources
Your knowledge of the Sandbox SDK may be outdated. Prefer retrieval over pre-training for any Sandbox SDK task.
| Resource | URL |
|---|---|
| Docs | https://developers.cloudflare.com/sandbox/ |
| API Reference | https://developers.cloudflare.com/sandbox/api/ |
| Examples | https://github.com/cloudflare/sandbox-sdk/tree/main/examples |
| Get Started | https://developers.cloudflare.com/sandbox/get-started/ |
When implementing features, fetch the relevant doc page or example first.
Required Configuration
wrangler.jsonc (exact - do not modify structure):
{
"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 entry - must re-export Sandbox class:
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox'; // Required export
Quick Reference
| Task | Method |
|---|---|
| Get sandbox | getSandbox(env.Sandbox, 'user-123') |
| Run command | await sandbox.exec('python script.py') |
| Run code (interpreter) | await sandbox.runCode(code, { language: 'python' }) |
| Write file | await sandbox.writeFile('/workspace/app.py', content) |
| Read file | await sandbox.readFile('/workspace/app.py') |
| Create directory | await sandbox.mkdir('/workspace/src', { recursive: true }) |
| List files | await sandbox.listFiles('/workspace') |
| Expose port | await sandbox.exposePort(8080) |
| Destroy | await sandbox.destroy() |
Core Patterns
Execute Commands
const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }
Code Interpreter (Recommended for AI)
Use runCode() for executing LLM-generated code with rich outputs:
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"
Languages: python, javascript, typescript
State persists within context. Create explicit contexts for production.
File Operations
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');
When to Use What
| Need | Use | Why |
|---|---|---|
| Shell commands, scripts | exec() |
Direct control, streaming |
| LLM-generated code | runCode() |
Rich outputs, state persistence |
| Build/test pipelines | exec() |
Exit codes, stderr capture |
| Data analysis | runCode() |
Charts, tables, pandas |
Extending the Dockerfile
Base image (docker.io/cloudflare/sandbox:0.7.0) includes Python 3.11, Node.js 20, and common tools.
Add dependencies by extending the 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
Keep images lean - affects cold start time.
Preview URLs (Port Exposure)
Expose HTTP services running in sandboxes:
const { url } = await sandbox.exposePort(8080);
// Returns preview URL for the service
Production requirement: Preview URLs need a custom domain with wildcard DNS (*.yourdomain.com). The .workers.dev domain does not support preview URL subdomains.
See: https://developers.cloudflare.com/sandbox/guides/expose-services/
OpenAI Agents SDK Integration
The SDK provides helpers for OpenAI Agents at @cloudflare/sandbox/openai:
import { Shell, Editor } from '@cloudflare/sandbox/openai';
See examples/openai-agents for complete integration pattern.
Sandbox Lifecycle
getSandbox()returns immediately - container starts lazily on first operation- Containers sleep after 10 minutes of inactivity (configurable via
sleepAfter) - Use
destroy()to immediately free resources - Same
sandboxIdalways returns same sandbox instance
Anti-Patterns
- Don't use internal clients (
CommandClient,FileClient) - usesandbox.*methods - Don't skip the Sandbox export - Worker won't deploy without
export { Sandbox } - Don't hardcode sandbox IDs for multi-user - use user/session identifiers
- Don't forget cleanup - call
destroy()for temporary sandboxes
Detailed References
- references/api-quick-ref.md - Full API with options and return types
- references/examples.md - Example index with use cases
04 同仓库更多 Skills
Zotero
Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.
zoom-apps-sdk
Use when using Apps SDK.
youtube
Obtain accurate, timestamped YouTube video transcripts (preferring manual captions over auto-generated) as the primary deliverable, then derive summaries, key claims, or notes from that transcript. Use when the user provides a YouTube URL (or video ID) and wants the transcript, a faithful summary, key claims with attribution, timestamped notes, or "what does this video actually say". The skill is transcript-first: never substitute metadata, title, description, or search snippets for the spoken content. Triggers: "youtube transcript", "get the transcript of this video", "summarize this youtube video", "what did they say in https://youtube.com/...", "key claims from this talk".
yeet
Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.
x-post-creator
Create X-ready post threads and co-located story packages from the active conversation or referenced project material. Use when the user says turn this into an X-post, /x-post, make this into an X thread, or wants plain-language social posts with supporting images saved to docs/x-posts/[story-name]/.
x-api
Search, read, and write X posts through the local X API MCP server (the same backend used by the Codex x-api skill). Use for searching X/x.com, reading threads and replies, creating lists, staging/publishing posts for @alltheputs, finding high-visibility reply targets for research outreach, ingesting public context, or any request that mentions /x-api or "search X".