try-works/role-model / .agents/skills/sandbox-sdk
sandbox-sdk
VerifiedBuild 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.
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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |