Skip to content

try-works/role-model / .agents/skills/sandbox-sdk

sandbox-sdk

Verified

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.

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.

ResourceURL
Docshttps://developers.cloudflare.com/sandbox/
API Referencehttps://developers.cloudflare.com/sandbox/api/
Exampleshttps://github.com/cloudflare/sandbox-sdk/tree/main/examples
Get Startedhttps://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

TaskMethod
Get sandboxgetSandbox(env.Sandbox, 'user-123')
Run commandawait sandbox.exec('python script.py')
Run code (interpreter)await sandbox.runCode(code, { language: 'python' })
Write fileawait sandbox.writeFile('/workspace/app.py', content)
Read fileawait sandbox.readFile('/workspace/app.py')
Create directoryawait sandbox.mkdir('/workspace/src', { recursive: true })
List filesawait sandbox.listFiles('/workspace')
Expose portawait sandbox.exposePort(8080)
Destroyawait 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

NeedUseWhy
Shell commands, scriptsexec()Direct control, streaming
LLM-generated coderunCode()Rich outputs, state persistence
Build/test pipelinesexec()Exit codes, stderr capture
Data analysisrunCode()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 sandboxId always returns same sandbox instance

Anti-Patterns

  • Don't use internal clients (CommandClient, FileClient) - use sandbox.* 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

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 117kUpdated Claude CodeCodexVerifiedInstall