sandbox-sdk

by Cloudflare

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. npx skills add https://github.com/cloudflare/skills --skill sandbox-sdk Download ZIPGitHub2k

Cloudflare Sandbox SDK

Build secure, isolated code execution environments on Cloudflare Workers.

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.

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 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

• references/api-quick-ref.md - Full API with options and return types

• references/examples.md - Example index with use cases